Getting Started in 10 Minutes

Where this stands today: self-hosted · single-tenant · Claude-first. You run Feature Agent (FA) on your own machine or infrastructure, authenticated with your own Anthropic/Claude credentials. BYOC packaging, a hosted SaaS option, and Postgres-backed multi-tenant hardening are roadmap chapters — not shipped yet.

This is the fastest path from a clean machine to watching FA open its first draft PR. Every command below is copy-pasteable and matches this repo as it stands — for the full option set, see SETUP.md (install/config), USER_GUIDE.md (feature reference), and OPERATIONS.md (running it in production).

What you'll have at the end

A running FA instance, one enrolled project, and one submitted feature request that FA has autonomously implemented — tested, documented, and pushed as a draft pull request on GitHub — without you writing any code yourself.

Prerequisites

• Node.js 18+ and git
• Docker — RUNTIME=docker is FA's default sandbox: every agent run happens inside a container, never on your host (see the Trust Boundary note in CLAUDE.md). You'll build one image below.
• An Anthropic API key (from console.anthropic.com) — or a machine already logged in via claude login (Claude Code OAuth) if you'd rather use that instead. Either can authenticate the in-container agent (FA_AGENT_AUTH=api or oauth); this guide uses the simpler api path.
• A GitHub personal access token with Contents: Read and write and Pull requests: Read and write on the repo you'll enroll. Optional — without it FA still enrolls the project and implements the feature, it just won't open a draft PR at the end.
• A repo to enroll, and its SSH remote URL (git@github.com:you/repo.git). FA clones over SSH using the host machine's own SSH key, not HTTPS — that key needs push access to the repo. A small/throwaway repo is fine for this walkthrough (see SETUP.md § Prerequisites).

1. Clone and install

git clone https://github.com/scottallan/featureagent.git
cd featureagent
npm install

2. Configure .env

cp .env.example .env

Edit .env — this is the minimum viable set for this walkthrough:

PORT=3100
ANTHROPIC_API_KEY=sk-ant-...      # required for FA_AGENT_AUTH=api (the default)
GITHUB_TOKEN=ghp_...              # optional — skip it and just drop the draft-PR step below
ADMIN_API_KEY=some-long-random-string

About ADMIN_API_KEY: if you leave it blank, FA self-provisions a random one on first startup and writes it into .env for you (the value is never logged — only the fact that it happened). Setting it yourself here is simpler for a first run, since you'll know the value up front.

About the sandbox default: RUNTIME=docker (already the default in .env.example) means every feature implementation runs inside a container FA starts — that's why step 3 below exists. .env.example also documents RUNTIME=local, which skips the sandbox entirely and runs the agent on the host; don't use it outside of a trusted dev box (see the Trust Boundary core law in CLAUDE.md).

3. Build the sandbox runtime image

docker build -t fa-runtime:latest containers/fa-runtime

Required before your first feature run — RUNTIME=docker expects this image (tag fa-runtime:latest, matching FA_RUNTIME_IMAGE in .env.example) to already exist; the first run fails with an actionable error otherwise.

4. Start Weftra

npm run build && npm start

(or npm run dev for hot-reload during exploration). You should see:

[featureagent] API server running on 127.0.0.1:3100

The dashboard is at http://localhost:3100 (binds to loopback only by default — nothing here is exposed to your network).

5. Enroll a project

curl -s -X POST http://localhost:3100/api/projects \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "repo_url": "git@github.com:you/repo.git",
    "autonomy_mode": "full_auto",
    "auto_create_pr": true
  }'

• repo_url must be the SSH form (git@host:owner/repo.git) — FA rejects HTTPS remotes.
• autonomy_mode: "full_auto" skips analysis/approval so this first feature goes straight to work; auto_safe and po_approval add an analysis and/or approval step ahead of it (see USER_GUIDE.md § Autonomy Modes).
• auto_create_pr: true is required to get a draft PR out the other end — it defaults to off. Omit it (or set GITHUB_TOKEN blank) if you skipped the GitHub token above.

The response is the created project, including api_key (an fa_... token) — this is the only time the full key is returned. Save it:

export PROJECT_API_KEY=fa_...   # the api_key field from the response above

Instead of curl, you can do the same from the dashboard: open http://localhost:3100, paste your ADMIN_API_KEY into the login box, and use the "Enroll Project" form.

6. Submit a feature

curl -s -X POST http://localhost:3100/api/features \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add a health-check endpoint",
    "description": "Add a GET /healthz route that returns HTTP 200 with body {\"status\":\"ok\"}."
  }'

Only title and description are required. The response includes the feature id; with full_auto it goes pending → queued immediately — no clarifying questions to answer.

7. Watch it land as a draft PR

The agent loop polls for queued work every AGENT_POLL_INTERVAL_MS (default 30s). Watch progress either in the dashboard (open the feature, live logs stream while it's in_progress), or by polling the API:

curl -s http://localhost:3100/api/features/<id> \
  -H "Authorization: Bearer $PROJECT_API_KEY"

Look at status — it moves queued → in_progress → implemented. Once implemented, and if you set GITHUB_TOKEN + auto_create_pr: true, pr_url is populated with a link to a draft pull request on GitHub, containing the implementation, tests, and docs the agent wrote. That PR is yours to review, request changes on, or merge — FA never merges for you.

What you just proved

• A tenant-scoped API key (fa_...), not an operator credential, drove the whole flow.
• The implementation ran inside a sandboxed container, never on your host.
• What shipped is attributable: which feature, which project, which run — see USER_GUIDE.md for the audit/provenance trail behind it.

Where to go from here

• Setup guide — every configuration option: notification channels, GitHub/GitLab/Bitbucket integration, Spec-Kit, permissions, model selection, users & roles, production deployment.
• User Guide — the full feature reference: autonomy modes, clarifications, revisions, workspace data provisioning, fleet fan-out, and more.
• Operations runbook — running FA in production: systemd, the trust boundary, secrets management, the self-build loop.
• SWE-bench-lite provisional report — how FA measures itself against a real benchmark; this guide makes no benchmark claim of its own.