Documentation
Configuration
Every setting is an environment variable with a safe default.
Environment variables
The orchestrator reads these variables. All of them are optional.
| Variable | Default | Purpose |
|---|---|---|
FOREMAN_DATA_DIR | ~/.foreman | Base folder for the database and worktrees |
FOREMAN_DB | <data>/foreman.db | SQLite database path |
FOREMAN_WORKTREES | <data>/worktrees | Where isolated task worktrees are created |
FOREMAN_HOST | 127.0.0.1 | Bind host. Loopback by default; remote access is opt-in |
FOREMAN_PORT | 4319 | HTTP and WebSocket port |
FOREMAN_SECRETS | os | os (Keychain or Credential Manager) or memory (tests) |
FOREMAN_MAX_ARTIFACT_BYTES | 104857600 | Largest worker output the Library captures (100 MB). Larger files are skipped and reported on the task timeline |
Where things live
Data folder
~/.foreman/
foreman.db # tasks, sessions, approvals, activity
worktrees/ # one folder per task, on its own branch
token # the API token, when one is configuredSecrets
With FOREMAN_SECRETS=os, capability keys and tokens are kept in the macOS Keychain or the Windows Credential Manager. They are never written to the database, never logged, and resolved into a private file only when a worker needs them.
Remote access
Foreman binds to 127.0.0.1. To reach it from your phone, put it on your private tailnet; plain network access still requires the token.