For a fresh environment, start with the preflight and resumable installer. It handles explicit interpreter selection, packaging upgrades, the MCP/test lock and checks in one fail-fast command. The manual sequence below remains available for reviewed development environments and troubleshooting.
Use the commands below from the Forge checkout, one block at a time. Stop on
any failed command. Blocks omit shell comments: interactive zsh may interpret a
pasted # line as a command and report zsh: command not found: #.
The package declares requires-python = ">=3.12"; Python 3.9 is unsupported.
The CI workflow targets Python 3.12, and the
historical Mac validation records Python 3.14.8.
There is no multi-version support matrix: the minimum declaration does not prove
that every newer interpreter works with the pinned dependencies. Prefer a
versioned Homebrew Python 3.12 for a new Mac environment to match CI.
Check the host and available tooling first:
hostname
command -v brew
command -v python3
python3 --versionA fresh Mac may have no Homebrew. If brew is missing, check whether
/opt/homebrew/bin/brew already exists before installing another copy. If absent,
follow the official Homebrew installation instructions,
including the installer's shell setup steps, then repeat the checks.
Homebrew's default Apple Silicon prefix is /opt/homebrew; use the actual
prefix on other installations.
Install versioned Python 3.12 if it is not already available:
brew list --versions python@3.12If absent:
brew install python@3.12Select its interpreter explicitly; do not rely on an unversioned python3:
FORGE_PYTHON="$(brew --prefix python@3.12)/bin/python3.12"
"$FORGE_PYTHON" --versionBefore creating a virtual environment, check for an existing one:
test ! -e .venv && test ! -L .venvIf this check fails, preserve the environment and inspect
.venv/bin/python --version and .venv/pyvenv.cfg. Do not delete or rebuild an
environment used by a running service. A working supported environment can be
reused; a failed or unsupported one needs a deliberate replacement after stopping
its users and preserving its version details. Do not copy a virtual environment
from another Mac.
For a new environment only:
"$FORGE_PYTHON" -m venv .venvUpgrade packaging tools before the editable pyproject installation, then install the full test/MCP dependency set, matching CI:
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements-mcp.lock
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python -m pip check
.venv/bin/python -m pytest -qrequirements-mcp.lock includes requirements.lock and pins the optional
MCP SDK. The core lock includes pytest but omits MCP; a controller-only runtime
can use it, but the current full test suite imports MCP in
test_native_mcp_submission. Install the MCP lock before running that suite or
using the MCP bridge. Do not change pins merely to bypass an installation
error. Record the interpreter, pip version, failing command and final test summary:
.venv/bin/python --version
.venv/bin/python -m pip --version
git rev-parse HEADNo global Python packages are required. Keep local secrets and task state outside
Git; .secrets/ and state/ are ignored.
Operator-provided output in the “Install Forge Dependencies” chat and follow-up request reported:
- The fresh Mac initially had no
brew. - Unversioned
python3resolved to/usr/bin/python3, Python 3.9.6;/opt/homebrew/bin/python3reported Python 3.15.2. - pip 21.2.4 rejected editable installation of the pyproject-only project.
Dependency installation also failed to resolve
annotated-types==0.8.0, and pytest was then unavailable. The cause of that resolution failure was not independently established; old pip alone is not a confirmed explanation. - A later installation reported
forge-controller-0.1.0installed and 334 passed, 1 failed, 1 skipped. The failure wasModuleNotFoundError: No module named 'mcp'intests/test_native_work_orders.py::test_native_mcp_submission. - Pasted shell comments produced
zsh: command not found: #.
Source inspection confirms the Python minimum, CI's Python 3.12/MCP-lock install, the MCP pin and that test's SDK import. Installing the MCP lock is the prescribed next step; no successful Foundry rerun, complete Python 3.15.2 validation, model installation, private-config migration, service startup or reboot acceptance has been observed here. Test counts can change with the checkout revision.
Before creating credentials or starting a replacement controller, inspect existing private configuration, source grants, database, MCP token and handoff journal on both hosts. Preserve the Macbox identities and task history. Use the backup/recovery workflow to verify a private snapshot and stage recovery separately; do not overwrite Foundry state or copy an active raw SQLite file. Reconcile host-specific source paths and the journal's endpoint identity before cutover. Keep uncertain submissions and receipts; do not replay them. Reuse or deliberately migrate approved credentials rather than generating a fresh production principal set. Do not publish private files or token values.
After dependencies/tests pass, inspect ollama list and download only missing
configured models. Validate the staged private profile before
service installation. Foundry does not become authoritative
until migration and authenticated runtime checks succeed.
For development, create a credential without printing it:
.venv/bin/python - <<'PY'
import json, secrets
from pathlib import Path
folder = Path('.secrets')
folder.mkdir(mode=0o700, exist_ok=True)
path = folder / 'principals.json'
if path.exists():
raise SystemExit('Credential file already exists; preserving it.')
path.write_text(json.dumps({'operator': {'token': secrets.token_urlsafe(32),
'agents': ['forge'], 'services': ['prototype']}}, indent=2))
path.chmod(0o600)
PYEach principal needs a unique random bearer token of at least 32 characters, an agents list containing forge, repository_analyst, and/or implementer, and services: ["prototype"] or []. An optional repositories list grants explicit repository IDs. Unknown fields are rejected. The file must have owner-only permissions. Never paste tokens into Git, commands, URLs, logs, or PRs. Rotate/revoke by editing the private file and restarting the controller; in-flight tasks should be stopped during revocation.
For a verified snapshot restore or direct private-network HTTPS, follow the migration procedure. The launcher defaults to loopback; non-loopback binding requires TLS and existing authentication.
If Ollama is not already running, start it in another terminal using the installed binary:
OLLAMA_HOST=127.0.0.1:11434 OLLAMA_NO_CLOUD=1 OLLAMA_NUM_PARALLEL=1 \
OLLAMA_MAX_LOADED_MODELS=1 OLLAMA_CONTEXT_LENGTH=4096 ollama serveDownload qwen3:8b and qwen3-coder:30b if missing. Do not run a second Ollama
instance on the same port. Copy the reviewed local profile once, preserving any
existing operator configuration:
test -e .secrets/local-controller.json || cp config/local-controller.example.json .secrets/local-controller.json
chmod 600 .secrets/local-controller.json
.venv/bin/python scripts/controller.py startThe launcher validates the private configuration, starts one foreground controller
on loopback, and records its process under ignored state/. The profile preserves
8B analysis, the coding-model implementer, explicit source grants and reviewed
examples. Paths are relative to the checkout, independent of the invoking directory.
Credentials remain in the separate private principal file; the profile contains
only settings and file paths. Remove optional manifest/example settings if you
have not configured those features. The launcher starts no Ollama process and
installs no login/background service. Stop an older manually launched controller
before first adopting it. Logs remain in the start terminal.
From another terminal, use:
.venv/bin/python scripts/controller.py status
.venv/bin/python scripts/controller.py stopCtrl+C in the start terminal also stops the controller cleanly. Duplicate managed
starts are rejected. Stop verifies the recorded process command before signaling
it and never stops an unrelated Ollama instance. Ollama remains available; unload
models with ollama stop qwen3:8b and ollama stop qwen3-coder:30b when finished.
In another terminal from this checkout:
export FORGE_PRINCIPALS_FILE="$PWD/.secrets/principals.json"
export FORGE_CLIENT_PRINCIPAL=operator
.venv/bin/python -m forge_controller.client --status-tool \
'Check the prototype service with the status tool and identify whether the result is synthetic.'The convenience client reads the development principal file and prints a task ID and result. It is not a credential-distribution mechanism: remote clients should receive only their own token. Ctrl+C in the client requests task cancellation. A client wait timeout leaves the task addressable by its ID.
Set FORGE_REPOSITORIES_FILE to an operator-owned JSON manifest outside Git:
{
"forge": {
"root": "/absolute/canonical/path/to/forge",
"files": ["src/forge_controller/model.py", "src/forge_controller/config.py", "pyproject.toml"]
}
}Grant the intended principal agents: ["forge", "repository_analyst"] and repositories: ["forge"] in its private credential record. Submit an analyst task with agent: "repository_analyst" and tools: ["list_repository_files", "read_repository_file"]. The convenience CLI currently submits only the original forge tasks; use the HTTP API for analyst tasks. Configure an adequate tool budget (FORGE_TOOL_ROUNDS=8 was used for the first experiment).
The analyst can list only manifest entries and read up to 80 numbered lines per call (at most 12 KiB returned). A line is LF-terminated, exactly as git and editors number it; other Unicode line separators (form feed, U+2028 and similar) do not start a new line. Work orders reject sources containing carriage returns (unsupported_line_endings) because exact-replacement admission cannot rely on them. Approved files must be non-hidden .py, .md, or .toml sources. File reads are limited to 64 KiB, reject symlinks at every component, and reject non-regular/multiply-linked files and invalid UTF-8. Neither listing nor reading uses a command-execution tool. Selecting a source for the manifest is an operator responsibility: even source files may contain secrets and must be reviewed before granting access. Keep the manifest restricted to selected source files, not an entire home directory.
Every read rechecks principal repository permission, requested task capability, path membership, argument shape, and limits. Approved file/range metadata is audited without source content. A task cannot finish as an analyst without at least one successful source read (sources_not_read); this does not prove its conclusions are correct. Source content remains untrusted. Reports require senior review; see the first experiment.
The implementer role uses the same explicit source manifest and read tools, with separate instructions to return proposed patch text. Grant it only when intended by adding implementer to the principal's agents list. Submit with agent: "implementer" and tools: ["read_repository_file"] (listing is optional). It must successfully read a source before completing.
This role cannot apply patches, edit files, or execute commands. Returned patch text is untrusted: senior Forge reviews source applicability, syntax, scope, and behavior before applying it to an isolated checkout and running tests. Task status succeeded means a model response was returned, not that a patch was accepted or verified. See the first implementation experiment.
Optional role routing uses operator-owned configuration:
export FORGE_ROLE_MODELS='{"implementer":"qwen3-coder:30b"}'Install each selected model first. forge and repository_analyst then retain
FORGE_MODEL (8B by default), while implementer tasks use the coding model.
Unspecified roles use FORGE_MODEL; an empty mapping preserves previous behavior.
Only the three existing roles and nonempty model-name strings are accepted.
Clients cannot supply a model in task input. All inference rounds for a task use
its role's model, and a model_selection audit entry records that selection
without consuming the tool budget. Missing models fail; there is no runtime
fallback to another model. Readiness requires every effective role model installed
and checks tags without loading them. Evaluation reports record actual role models.
Keep the single controller worker and Ollama OLLAMA_NUM_PARALLEL=1 /
OLLAMA_MAX_LOADED_MODELS=1 settings shown above. The controller serializes its
tasks; Ollama manages loading and eviction. Those runtime limits are deployment
settings, not enforced against unrelated clients by the controller. Switching
roles can add model-loading latency. The larger model occupied about 17.6 GiB
with context 4096 in the prototype comparison.
| Setting | Default / requirement |
|---|---|
FORGE_PRINCIPALS_FILE |
Required path to private principal grants |
FORGE_REPOSITORIES_FILE |
Optional private path to explicit source manifest |
FORGE_DATABASE |
state/tasks.sqlite3; local disk owned by service account |
FORGE_MODEL_URL |
http://127.0.0.1:11434; trusted operator configuration |
FORGE_MODEL |
qwen3:8b |
FORGE_ROLE_MODELS |
JSON role-to-model mapping, default {} |
FORGE_EXAMPLES_FILE |
Optional reviewed example collection; see feedback loop |
FORGE_CONTEXT_LENGTH |
Positive integer; default 4096 context tokens |
FORGE_MAX_OUTPUT_TOKENS |
Positive integer; default 512 output tokens |
FORGE_TASK_TIMEOUT |
60 seconds of execution, measured from dispatch (queue wait is not counted) |
FORGE_QUEUE_TIMEOUT |
600 seconds a task may wait before dispatch; finite positive number. Expiry settles the task and frees capacity even while another task is running. |
FORGE_CAPACITY |
8 admitted tasks, including running work |
FORGE_TOOL_ROUNDS |
Maximum 3 total tool calls |
FORGE_CONTROLLER_URL |
Client URL, default http://127.0.0.1:8787 |
FORGE_CLIENT_PRINCIPAL |
Configured principal name; set explicitly (for example, operator) |
Model calls default to 4096-token context and at most 512 output tokens; both limits can be overridden at startup. Thinking is disabled, temperature is 0, and models unload after five idle minutes. Model responses are limited to 64 KiB; HTTP request bodies to 32 KiB; prompts to 8000 characters. One task runs at a time. There is no automatic external-model fallback. New limits must be actual positive integers; booleans/fractional/string programmatic values and malformed environment values are rejected. Operator overrides can increase memory use, output length, latency, and deadline risk; practical upper bounds need workload measurements.
All routes except liveness require Authorization: Bearer <token>. There is no public interactive documentation route.
| Route | Behavior |
|---|---|
GET /health/live |
Process liveness |
GET /health/ready |
Database write probe and configured model availability; no inference load |
POST /v1/tasks |
Accept { "agent": "forge", "prompt": "...", "tools": ["get_service_status"] }; tools default to none; return 202 and ID |
POST /v1/work-orders |
Submit a source-pinned order; immutable selected-file snapshot and structured result enforcement; see work orders |
GET /v1/tasks/{id} |
Owner-scoped task status, result, error, and tool audit |
POST /v1/tasks/{id}/cancel |
Cancel queued/running task; completed records remain terminal |
DELETE /v1/tasks/{id} |
Delete settled terminal record; 409 while active |
Statuses: queued, running, succeeded, failed, cancelled. Errors include model_unavailable, invalid_model_response, tool_denied, tool_limit_exceeded, deadline_exceeded (execution exceeded its limit), queue_expired (waited too long before dispatch; no inference ran), and interrupted. Unknown or another owner's ID returns 404. Invalid credentials return 401; forbidden capability requests 403; invalid input 422; large bodies 413; full admission capacity 503. Cancellation prevents result publication but cannot undo a remote action; only synthetic read-only actions exist here.
Stop with Ctrl+C in the server terminal. Active tasks become interrupted; startup also reconciles records left by abrupt termination. No automatic replay. Do not run --reload, multiple workers, or concurrent replicas against this database. Keep the database directory private; task results may contain sensitive content. Logs are JSON lifecycle metadata with task IDs, without prompts, responses, credentials, or raw tool arguments. Configure rotation/retention in the chosen launcher before prolonged operation.
The Mac prototype uses the user-login service manager for
Ollama and the controller. To run on Ubuntu, install the same Python environment
and checkout under a dedicated non-admin service account. Place private grants
outside the checkout, set absolute database/config paths, and use a single
systemd service process with explicit working directory/environment and restart
throttling. Ubuntu service installation and VM deployment remain later steps.
For a controller on another host, keep raw Ollama on loopback and use a restricted SSH tunnel or an authenticated TLS gateway. Update FORGE_MODEL_URL accordingly. Do not expose raw Ollama, publish controller ports to the Internet, or use unencrypted bearer tokens across an untrusted network. Reuse existing private networking. Verify the deployment host firewall and access restrictions before enabling network access.
Use the private backup and recovery workflow for consistent live SQLite snapshots and private configuration. Stop the managed services before any manual raw database copy. Validate restores in a separate private directory and instance before production replacement. Preserve runtime/model manifests and dependency versions; exclude reproducible model caches from routine source backups.
There is no automatic retention scheduler in this release. Delete terminal task records through the owner-scoped endpoint and establish retention before ingesting personal data. Deletion is logical; it does not erase existing backup copies or guarantee forensic removal. Full disk/database failure may prevent durable status writes; recover disk/storage first, then restart and reconcile. Do not claim acceptance until backup/restore and failure scenarios are validated in the target deployment.
Native work orders migrate the database to version 2. Back up before upgrade; an older controller requires a pre-upgrade restore. Generic tasks remain compatible. See native scope, retention and rollback.