Weftra

Appearance

Getting Started in 10 Minutes ​

Where this stands today: self-hosted · single-tenant · Claude-first. You run Weftra (Weftra) 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 Weftra 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 Weftra instance, one enrolled project, and one submitted feature request that Weftra 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 Weftra'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 Weftra 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). Weftra 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).

Fastest path: Docker Compose ​

If you would rather not install Node, run Weftra from the repo's docker-compose.yml. This is the flow npm run rehearse:install validates end to end (deploy/rehearsal/compose.ts). It still needs the runtime image from step 3 below.

bash
git clone https://github.com/weftra/weftra.git
cd weftra
cat > .env <<'EOF'
PORT=3100
ADMIN_API_KEY=some-long-random-string
DATABASE_PATH=./data/weftra.db
WORKSPACE_DIR=./workspaces
ANTHROPIC_API_KEY=sk-ant-...
RUNTIME=docker
FA_RUNTIME_IMAGE=fa-runtime:latest
DOCKER_GID=999
EOF
docker build -t fa-runtime:latest containers/fa-runtime
docker compose up --build -d
curl http://localhost:3100/health

Set DOCKER_GID to your Docker socket's group (stat -c %g /var/run/docker.sock); the compose file mounts the socket so Weftra can start the sandbox containers. Then continue at step 5 (Enroll a project). The npm path below is the alternative.

1. Clone and install ​

bash
git clone https://github.com/weftra/weftra.git
cd weftra
npm install

2. Configure .env ​

bash
cp .env.example .env

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

env
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, Weftra 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 Weftra 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). Weftra refuses to start with RUNTIME=local unless you also set FA_LOCAL_RUNTIME_ACKNOWLEDGED=host-unsandboxed — in practice every local start needs it, because Weftra provisions ADMIN_API_KEY itself at boot (see docs/OPERATIONS.md §39).

3. Build the sandbox runtime image ​

bash
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.

That image is Node/TypeScript. A project on another toolchain (Python, Bun, Go, …) declares a different runtime_image; building and allowlisting one is a 20-minute recipe — see Runtime images.

4. Start Weftra ​

bash
npm run build && npm start

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

[weftra] 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 ​

You don't have to work out the project's configuration yourself. Weftra reads the repository first and proposes it.

  1. Open http://localhost:3100, paste your ADMIN_API_KEY into the login box, and click + Enroll Project.

  2. Enter a name and the repository's SSH URL (git@github.com:you/repo.git), then click Survey repository. The form is locked while the survey runs, and shows its progress until the proposal arrives.

  3. Weftra makes a shallow clone into a throwaway workspace and reads the files that describe how the project builds: CI workflows, task runners, package manifests, toolchain pins, Dockerfile, README, CONTRIBUTING, AGENTS.md/CLAUDE.md. It runs nothing from the repository. In a minute or so it fills in the form:

    • the default branch and the sandbox runtime image;
    • the setup, test and verify commands and the hosts the tests need to reach. Each comes with the file and line it was taken from, and Weftra checks that the line really says that before showing it;
    • a readiness verdict: anything that will make this repository hard for an agent, such as no CI, tests that need a secret or an outside service, or a contribution policy that rules out automated PRs, each with how to fix it.

  4. Change anything you disagree with. For this walkthrough set Autonomy mode to full_auto, and tick Auto-create Draft PRs if you set GITHUB_TOKEN above. Then click Save.

  5. Copy the API key Weftra shows. This is the only time the full key is shown.

    bash
    export PROJECT_API_KEY=fa_...   # the key from the dialog

  6. Optional: click Check on the project's row, then Run Check. Weftra runs the setup, test and verify commands in the sandbox, without implementing anything, and reports each step green or red. You find out whether the environment really works before an agent depends on it.

full_auto skips analysis and 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). The survey is described in full under "The enrolment survey" in the User Guide.

Or enroll with curl ​

The survey is also an API (POST /api/projects/propose with {"repo_url": "..."}, then read the report it links to). To skip it and enroll directly:

bash
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) — Weftra rejects HTTPS remotes.
  • auto_create_pr: true is required to get a draft PR out the other end — it defaults to off. Omit it if you skipped the GitHub token above.

The response includes api_key. It is returned in full only this once, so save it:

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

6. Submit a feature ​

bash
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:

bash
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 — Weftra 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.

Running it on your own: evidence, not ceremony ​

You do not need a team to get value from Weftra. Its governance controls — approval steps, separation of duties, named approvers — exist for organizations where more than one person acts on a change. A single developer can authorize their own work, and what they get from Weftra is mostly evidence: a verifiable record of what the agent did, what Weftra itself ran, and what was reviewed, attached to every change.

Running solo is configuration on the same instance, not a separate mode — a team later is a tighter setting of the same project, with the same evidence. There are two ways to set it up:

  1. No approval step. Enroll the project with autonomy_mode: "full_auto" (a feature goes straight to the queue) or "auto_safe" (the agent analyzes it first and may ask you clarifying questions). Nobody has to approve anything.

  2. Keep an approval step, and approve your own work. By default a submitter cannot approve their own feature. To allow it, an admin sets the project's separation policy so that pair is recorded rather than refused:

    bash
    curl -X PATCH http://localhost:3100/api/projects/$PROJECT_ID \
  -H "Authorization: Bearer $ADMIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"separation_policy": {"submitter_approver": "record"}}'

    A verified account may then approve a feature it submitted; Weftra records that the submitter and the approver were the same person instead of refusing the approval. An approval with no verified identity is still refused, and the policy change itself is recorded.

What does not change when you run alone — none of this depends on a second person:

  • Every agent run happens in the sandbox, never on your host.
  • Weftra runs your project's declared test command itself after the agent finishes; only Weftra's run counts as evidence, not the agent's own claim that tests passed.
  • You can add independent review passes to every pull request — a spec-conformance reviewer and an adversarial security reviewer. Both are opt-in (off by default) and set per project by an admin (reviewer: "spec_conformance", security_reviewer: "adversarial"); a solo developer is usually the admin too.
  • Each feature has an evidence pack (GET /api/features/:id/evidence-pack) you can verify against your instance's public key, and its PR carries a weftra/provenance check.
  • Every run writes to a tamper-evident, hash-chained ledger you can export (GET /api/audit/export).

When a second person joins, set submitter_approver back to "require" (or "require_proven") — the history you built alone stays exactly as it was.

Let it build your roadmap while you're away ​

For one developer, the bigger win is not approving individual changes — it is that Weftra can work through your roadmap on its own. You keep a backlog; Weftra's loop picks the next unblocked item, builds it, runs it through the same pipeline a manual submission gets, and hands you a pull request with its evidence attached. You set the direction; it does the next item.

  • You own the queue. The backlog is a document committed in your repo (backlog_path), or your project's Product Definition store (backlog_source: "definition_store"). Reordering it is how you steer — the loop always takes the next unblocked item, one per cycle.

  • You own the limits. An admin turns the loop on once for the project, with its cadence and a per-cycle budget, for example:

    bash
    curl -X PATCH http://localhost:3100/api/projects/$PROJECT_ID \
  -H "Authorization: Bearer $ADMIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"loop": {"enabled": true, "cadence_seconds": 7200, "budget_usd_per_cycle": 2, "backlog_path": "BACKLOG.md"}}'

    After that the project's own key can switch it off and on again, or point it at a different backlog file.

  • You own the merge. By default (merge_policy: "human_all") every PR the loop opens waits for you to merge it — there is no autonomous-merge path at all in that mode. An admin can opt the project into merge_policy: "auto_low_risk", which merges only the diffs that are conservative on every signal and parks everything else exactly the same way.

  • The evidence is what makes it safe to look away. You did not watch these changes being made, so each one carries what you need to trust it after the fact: the sandboxed run, Weftra's own test run, any review passes you turned on, the evidence pack and the ledger.

Weftra's own development works the same way: a self-build loop takes the next item from Weftra's roadmap, and it has built most of the platform's recent changes, each with the same evidence trail. (Today that loop is a separate harness; moving Weftra itself onto this per-project loop is in progress.) See USER_GUIDE.md ("The Weftra-native loop") for every loop setting.

Where to go from here ​

  • Drive it from your assistant — connect Claude Code, Claude Desktop, claude.ai, ChatGPT or any MCP client, and submit and track features from a chat.
  • 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 Weftra in production: systemd, the trust boundary, secrets management, the self-build loop.
  • SWE-bench-lite provisional report — how Weftra measures itself against a real benchmark; this guide makes no benchmark claim of its own.

Released under the MIT License.