Skip to main content
FeatureFactory
Docs Local Runner
Browse documentation

Docs

Local Runner

Execute FeatureFactory work orders from your own machine using Claude Code as the agent. No cloud VM. No uploaded code. Your environment, your credentials, your billing.

Install

Run the initialisation wizard without installing the package globally:

npx @featurefactory/runner init

Or install globally first:

npm install -g @featurefactory/runner
featurefactory-runner init

What init does

  1. 1Prompts for your FeatureFactory API URL, API key, runner name, and type.
  2. 2Writes ~/.featurefactory/runner.json with your configuration.
  3. 3Registers your runner with the FeatureFactory API and stores the returned runner_key back into runner.json.
  4. 4Registers the MCP server entry in ~/.claude.json (primary) and .mcp.json in the current directory (fallback) so Claude Code discovers the runner automatically.

Adding repositories

After init, add repo paths to the repos map in ~/.featurefactory/runner.json: 

{
  "api_url": "https://featurefactory.com",
  "api_key": "ff_...",
  "runner_name": "my-machine",
  "runner_type": "local",
  "runner_key": "...",
  "repos": {
    "your-org/your-repo": "/home/you/code/your-repo",
    "your-org/other-repo": "/home/you/code/other-repo"
  }
}

Repo paths are stored locally only. They are never sent to the FeatureFactory server in any API request.

After rotating an API key

When you rotate a key in FeatureFactory Settings, the old key stays valid for 24 hours then is automatically revoked. You must update the runner config before the grace period ends:

  1. 1Copy the new key from the Settings page immediately after rotation - it is shown only once.
  2. 2Open ~/.featurefactory/runner.json and replace the api_key value with the new key.
  3. 3Alternatively, re-run npx @featurefactory/runner init to go through the full setup wizard with the new key.

Claude Code skills

Two skills are bundled and installed automatically. Open Claude Code in any directory after init and run either command.

/factory-workerRecommended for continuous operation

Polls the FeatureFactory API in a loop and executes work orders one at a time until the server sends a stop signal. Keep the Claude Code window open while the worker is running.

Loop actions

ActionBehaviour
claimInvokes /factory-claim to claim and execute the next work order.
waitSleeps for retry_after_seconds then polls again.
stopExits cleanly and prints a summary of completed orders.
/factory-claimSingle-order execution

Claims and executes exactly one work order, then stops. Useful for testing or manually picking a specific order.

Usage

/factory-claim
/factory-claim --type=feature
/factory-claim --id=42

What happens

  1. 1.Reads ~/.featurefactory/runner.json for the repos map.
  2. 2.Calls ff_claim_work to get a work order. If the target repo is not mapped, releases the order without burning an attempt.
  3. 3.Creates an isolated git worktree at {`{repo_path}-wo-{id}`} pinned to origin/{`{default_branch}`}.
  4. 4.Fetches context bundles via ff_get_context and launches a sub-agent inside the worktree.
  5. 5.Pushes the feature branch using your local git credentials and calls ff_complete_work. The FeatureFactory server opens the pull request.
  6. 6.Removes the worktree on both success and failure.

Security model

The runner is designed so that running it on a developer workstation requires no changes to network policy and no trust in a third-party cloud VM.

Outbound HTTPS only

The runner makes outbound HTTPS requests to the FeatureFactory API and GitHub only. No inbound ports are opened. Your firewall rules do not need to change.

Code is never uploaded

Your source code stays on your machine. The runner sends structured result payloads (branch name, work order ID, completion status) - not file contents or diffs.

API key scoped to work-orders

The API key stored in runner.json carries the work-orders:* scope only. It cannot access billing, team settings, members, or any other product data.

You pay your own tokens

The runner executes work orders inside your local Claude Code session. Token costs are billed to your Anthropic account, not FeatureFactory. You have full visibility into what each job consumes.

What leaves your machine

  • -Work order claim and completion requests (IDs, branch names, structured result payloads).
  • -Git push to your existing remote via your existing git credentials (same as running git push by hand).
  • -LLM API calls from the Claude Code session to Anthropic - billed to your Anthropic account, not FeatureFactory.

What never leaves your machine

  • -File contents or diffs.
  • -Absolute filesystem paths from the repos map.
  • -Environment variables, secrets, or any files outside the checked-out worktree.
Register a Local Runner, confirm its health, and review the execution policy before use.

Was this article helpful?

Your response enters the same customer insight queue used by product feedback.