Forge

Forge is a local, MCP-native runtime for investigating and repairing Python and pytest repositories. It runs an agent in an isolated Git worktree, preserves an auditable SQLite event trail and artifacts, and never commits, pushes, opens a pull request, or applies a patch back to the original working tree.

Forge v1.0 is the first stable public release. Its first-party forge-repo-mcp server is the supported tool surface today; the runtime itself remains independent of that particular repository workload.

What it provides

• Provider profiles through LiteLLM (tested with DeepSeek tool calling).
• A single-agent model/tool loop with runtime-enforced policy and budgets.
• A durable --read-only contract that hides command and write tools from the model, rejects shell verification, and can be narrowed with repeated --allow-tool options.
• Bounded model context with a completed-tool ledger, per-turn tool limits, cached read-only evidence, consecutive no-progress detection, and a reserved final synthesis turn.
• Docker-by-default execution with no network, dropped Linux capabilities, a read-only base filesystem, a writable isolated worktree, and CPU/memory/PID limits.
• Isolated Git worktrees, patch/report artifacts, JSONL-style event history, SQLite inspection, checkpoints, and resume.
• Deterministic development and frozen fault scenarios for model timeout, tool timeout, prompt injection, and a lost patch response.

Read the architecture and security boundary before using Forge on a repository that matters.

Requirements

Install these prerequisites before the first run:

• Python 3.12 or 3.13.
• uv for the locked Python environment.
• Git and a Git repository you are authorized to inspect.
• Docker Desktop on Windows, or Docker Engine on Linux.
• An API key for the model provider you intend to use.

Docker must be running before forge prepare or forge run. Installing Docker Desktop is not enough: wait until its Linux engine reports that it is ready.

Quick start: from clone to a working task

1. Clone and install all dependencies

git clone <repository-url>
cd forge
uv sync --locked --all-groups

uv sync --locked --all-groups installs the exact locked runtime, development, and test dependencies in one step. You do not need to install the Python packages individually.

Confirm that the CLI is installed and discover its built-in help:

uv run forge --help
uv run forge models --help

2. Start and verify Docker

Start Docker Desktop on Windows. On a systemd-based Linux host, start Docker Engine with:

sudo systemctl start docker

Then verify the client can reach the engine:

docker version
docker info

docker version must show both a Client section and a Server section. If the Server section is missing, reports a named-pipe/socket error, or Docker Desktop still says “starting,” do not run Forge yet. Start or restart Docker and repeat the check.

3. Configure a model profile

Set the provider key in your current shell, then save a named profile. Forge stores the environment variable name, provider, and model identifier; it does not store the API key value.

$env:DEEPSEEK_API_KEY = "<your-api-key>"
uv run forge models add deepseek `
  --provider deepseek `
  --model "your-model-id" `
  --api-key-env DEEPSEEK_API_KEY

The profile name deepseek is a local label used by later commands. Keep real keys out of TOML, task text, commits, issue descriptions, and terminal screenshots.

4. Validate the profile

uv run forge doctor --profile deepseek
uv run forge doctor --profile deepseek --probe

The first command performs a local configuration and credential check without printing the key. --probe is optional and sends one minimal real tool-calling request to the provider.

5. Build the Docker runner

Make sure Docker is running, then build the cached, networkless MCP runner image:

uv run forge prepare

Run prepare again after updating Forge source or runner dependencies. A successful build creates the default forge-runner:test image used by forge run.

6. Run a safe first investigation

Start with read-only mode so the model cannot execute commands or change repository files:

uv run forge run <repository-path> `
  --profile deepseek `
  --read-only `
  --allow-tool repo.list_files `
  --allow-tool repo.search `
  --allow-tool repo.read_file `
  --task "Analyze the project structure and identify the least-tested core module."

<repository-path> must be the root of an existing Git working tree. Forge creates a detached, isolated worktree and prints a run ID. It does not modify the original working tree.

7. Inspect and export the result

Replace RUN_ID with the ID printed by forge run:

uv run forge inspect RUN_ID
uv run forge export RUN_ID --output .\forge-exports

Inspection displays persisted state, events, and artifacts. Export writes a human-reviewable patch, report, and trace without applying or committing the patch.

Choosing a run mode

Read-only investigation

Use this mode for architecture reviews, code search, dependency analysis, or any task that must not execute repository commands or write files:

uv run forge run <repository-path> `
  --profile deepseek `
  --read-only `
  --allow-tool repo.list_files `
  --allow-tool repo.search `
  --allow-tool repo.read_file `
  --task "Explain the authentication flow and identify its main risks."

Do not combine --read-only with --verify; the immutable run contract rejects that combination.

Repair with verification

For an authorized repair, provide explicit verification commands and protect sensitive paths:

uv run forge run <repository-path> `
  --profile deepseek `
  --task "Find and fix the failing login test; do not change the public API." `
  --verify "python -m pytest tests/test_login.py" `
  --protect api/public_schema.py

Repeat --verify for multiple commands and --protect for multiple repository-relative paths. Forge keeps the resulting patch in the isolated worktree and artifacts for human review.

Command reference

Use the top-level help to see the installed command set, and append --help to any command for its complete arguments and options:

uv run forge --help
uv run forge COMMAND --help

Command	Purpose	Typical use
uv run forge models add	Save a non-secret named provider profile.	Run once per provider/model configuration.
uv run forge doctor	Validate profiles and required key variables.	Run before a task; add --probe for a real provider check.
uv run forge prepare	Build or refresh the Docker runner image.	Run before the first task and after runner updates.
uv run forge run	Start a new isolated repository task.	Supply a repository, profile, task, and optional safety constraints.
uv run forge resume	Continue a paused run from its checkpoint.	Use --approve only for the exact recorded approval request.
uv run forge inspect	Display persisted state, events, and artifacts.	Diagnose a run without changing it.
uv run forge export	Export patch, report, and trace files.	Review or share evidence without applying changes.
uv run forge eval	Grade persisted fixture runs.	Run deterministic development and frozen fault evaluations.

Useful command-specific help pages include:

uv run forge models --help
uv run forge run --help
uv run forge resume --help
uv run forge inspect --help
uv run forge export --help
uv run forge eval --help

Run records, inspection, and recovery

Run records are grouped under ./run-records/runs/<run-id>/. Each run stores a SQLite record, JSONL-style events, checkpoints, and text artifacts. To use a different root, pass --storage <storage-path> to run and reuse the same value with later commands.

Inspect a run

uv run forge inspect RUN_ID --storage <storage-path>

Use inspection first when a task fails or pauses; the recorded events distinguish model, tool, policy, and sandbox failures without replaying the task.

Resume a paused run

uv run forge resume RUN_ID --storage <storage-path>
uv run forge resume RUN_ID --approve --storage <storage-path>

Use --approve only when inspection shows a recorded approval request and you understand the exact operation. Failed and completed runs are not general-purpose resumable sessions.

Export artifacts

uv run forge export RUN_ID --storage <storage-path> --output .\forge-exports

The export directory must not already contain a conflicting run export. Review every generated patch before applying it outside Forge.

Troubleshooting

McpError: Connection closed or an AnyIO cancel-scope traceback

This usually means the Docker subprocess exited before the MCP initialization handshake. The first thing to check is whether Docker Desktop or Docker Engine is actually running. A later message such as Attempted to exit cancel scope in a different task is cleanup noise after the connection closes; look earlier in the terminal for the Docker error.

1. Run docker version and confirm that it includes a Server section.
2. Run docker info; named-pipe, socket, or “cannot connect to daemon” errors mean Docker is not ready.
3. Start or restart Docker Desktop/Engine and wait for it to become healthy.
4. Run uv run forge prepare to build or refresh the runner image.
5. Retry the original forge run command.

docker version
docker info
uv run forge prepare

If Docker is healthy but the connection still closes, check that the runner image exists with docker image inspect forge-runner:test, then run prepare again and inspect the earliest container error rather than the final cleanup traceback.

Model profile or credential errors

Use doctor without --probe first. It checks profile names and environment variables locally and does not print secret values:

uv run forge doctor --all
uv run forge doctor --profile deepseek

If the key variable is missing, set it in the same shell that runs Forge. If the profile is missing, create it with models add. Use --probe only after the local check passes.

forge prepare cannot build the image

Confirm Docker is healthy and has enough disk space, then rerun the build:

docker info
uv run forge prepare

The build uses locked, hashed dependencies. Network, registry, proxy, or certificate failures during prepare are Docker build problems; they occur before a repository task starts.

uv reports that hardlinks are unavailable

The “Failed to hardlink files; falling back to full copy” warning is not a Forge failure. Installation continues with file copies and may only use more time and disk space. To suppress it intentionally:

$env:UV_LINK_MODE = "copy"

Evaluation and development

The repository contains six development fixtures and four frozen fault fixtures. forge eval deliberately reports zero evaluated scenarios until you provide persisted run IDs; it never invents model results.

uv run forge eval fixtures/dev
uv run forge eval fixtures/frozen
uv run pytest
uv run ruff check src tests
uv run pyright

Release check

On Windows with Docker Desktop running, execute the reproducible v1.0 gate from a clean Git worktree:

.\scripts\release-check.ps1 -Profile deepseek

It creates a temporary environment from uv.lock, runs the full test and eval suite, validates the Docker runner, and completes an isolated live provider demo. See the release checklist for exact acceptance criteria.

Safety model and limitations

Docker isolation and runtime policy reduce risk; they do not guarantee that arbitrary, untrusted code is safe. Forge treats repository content, test output, and tool output as untrusted input. Review exported patches and reports before use. Only the local Docker-backed first-party MCP server is supported in v1.0.

For the exact controls and remaining limitations, see docs/security.md.

Project governance

• Report vulnerabilities privately according to SECURITY.md.
• Read CONTRIBUTING.md before opening a pull request.
• Usage and issue-routing guidance lives in SUPPORT.md.
• User-visible changes are recorded in CHANGELOG.md.

License

Forge is open source under the MIT License.