Configuration¶
All settings come from environment variables (loaded from .env by Bun; a
shell variable overrides the file). See .env.example for the annotated list.
Required¶
| Variable | Purpose |
|---|---|
DATABASE_URL |
Postgres connection string (matches docker-compose.yml) |
ENCRYPTION_KEY |
32+ random characters; derives the AES-256-GCM key that seals OAuth tokens. Rotating it invalidates every stored token. |
Models (bring your own key)¶
Spaces ships without model access: you bring the keys of the providers you pay for and usage is billed to those accounts.
| Provider | Get a key | Notes |
|---|---|---|
| Anthropic | console.anthropic.com → API keys | Claude models directly (sk-ant-…) |
| OpenAI | platform.openai.com → API keys | GPT models directly; also serves knowledge-base embeddings (sk-…) |
| OpenRouter | openrouter.ai → Keys | One key for every vendor; OpenRouter routes each request itself (sk-or-…) |
LLM provider keys are entered under
Organization → Models, stored encrypted with ENCRYPTION_KEY and verified
when saved; they are not environment variables. No model is configured by
name either. Spaces routes automatically for the provider in use: it scores that provider's chat models by price, generation and size
class and fills three tiers — small (review, chat, fast mode), medium
(planning and implementation) and large (quality mode, retry escalation).
The organization policy under Organization → Models tunes it: preference
(cost / balanced / quality), provider order, whether premium ("pro") models
may be used, and optional pins per tier. With OpenRouter first in the order
every tier is openrouter/openrouter/auto and OpenRouter routes each request
itself. Templates that still pin a model from a provider without a key fall
back to the same-size tier.
| Variable | Default | Purpose |
|---|---|---|
EMBEDDING_MODEL |
openai/text-embedding-3-small |
Embedding model for the organization knowledge base; served by OPENAI_API_KEY, or through OpenRouter (OPENROUTER_API_KEY) for openai/* and openrouter/<vendor>/<model> ids. Without a usable key, knowledge search is full-text only. |
EMBEDDING_DIMENSIONS |
1536 |
Size of the vector column; must match the model's output |
Optional¶
| Variable | Default | Purpose |
|---|---|---|
PORT |
3000 |
Web UI + API port |
PUBLIC_URL |
unset | Public origin behind a TLS-terminating proxy, for OAuth callbacks, GitHub App manifests and invite links; the forwarded headers are honoured when unset |
WORKER_ID |
random UUID | Worker identity (per process) |
WORKER_MAX_CONCURRENT_JOBS |
4 |
Jobs one worker runs at once across projects |
SUPERVISOR_MAX_WORKERS |
4 |
SPACES_ROLE=all: cap on the supervisor's per-project job processes (each ~300–500 MB) |
WORKER_IDLE_EXIT_SECONDS |
300 |
SPACES_ROLE=all: idle time before a supervisor's job process exits |
PROJECT_WORKERS_MAX_AWAKE |
5 |
Worker per project: how many workers may run jobs at once |
PROJECT_WORKER_IDLE_SECONDS |
300 |
Worker per project: idle time before a worker's job process stops (and the service can sleep) |
AIDLC_WORKSPACE_ROOT |
~/.aidlc/workspaces |
Where GitHub repos are cloned (<owner>/<name>) |
SPACES_BROWSER_PATH |
Playwright's bundled Chromium, else a system Chromium/Chrome | Override the Chromium binary for the agents' built-in browser tools |
PLAYWRIGHT_BROWSERS_PATH |
Playwright default (~/.cache/ms-playwright) |
Where playwright install chromium puts browsers; the Docker image uses /ms-playwright |
AIDLC_GOVERNANCE_WORKSPACE |
1 |
0 keeps specs inside the application repo instead of a governing workspace |
AIDLC_GOVERNANCE_ROOT |
<workspace root>/_governance |
Location of governing workspaces |
AIDLC_WORKTREE_ROOT |
<repo>/.aidlc-worktrees |
Where workstream worktrees are created |
AGENT_DATABASE_URL |
the application's database server | Server on which each checkout's test database (agent_<checkout>) is created |
AGENT_COMMAND_TIMEOUT_SECONDS |
1200 |
Longest any shell command an agent runs may take (minimum 60) |
RAILWAY_DEPLOYMENT_DRAINING_SECONDS |
Railway default | How long a deploy lets a running stage finish before the old container stops (set it to about 900) |
The package-manager caches agents use (bun, npm, yarn, pnpm, pip, Go) live in
<workspace root>/../cache, on the same volume as the workspaces, unless a
project sets its own.
Agent tracing (Arize Phoenix)¶
Every agent session can be traced to Arize Phoenix:
pipeline stages, tasks, workstreams, sub-agents, development setup and the
project assistant. Each agent turn is one trace: an agent span (the turn's
input and answer) with a child span for the model response (model, tokens,
cost, output) and one per tool call (arguments, result, errors), named like
stage · implement · turn 12. Turns are sent as they finish, so traces appear
while a stage runs; a turn cut off by a restart is sent marked interrupted.
Spans carry the organization, project, stage, prompt and turn, and the run is
the Phoenix session, so one run's turns read as one conversation (Sessions
tab). Text is masked
by the organization's data guardrails, secrets are always redacted, and long
text is cut to 16,000 characters.
| Variable | Default | Purpose |
|---|---|---|
PHOENIX_COLLECTOR_ENDPOINT |
unset (tracing off) | Phoenix base URL, e.g. http://localhost:6006 or http://phoenix.railway.internal:6006; spans go to <url>/v1/traces |
PHOENIX_API_KEY |
unset | Phoenix API key, when Phoenix runs with authentication |
PHOENIX_PROJECT_NAME |
spaces |
Phoenix project the traces land in |
PHOENIX_AUTO_PROVISION |
unset | 1 on a Railway web service with RAILWAY_PROVISIONER_TOKEN: Spaces creates Phoenix itself (below) |
Phoenix on Railway, automatically. With PHOENIX_AUTO_PROVISION=1 the web
service makes sure, on each start, that the Railway project has a phoenix
service: the arizephoenix/phoenix image, a volume at /mnt/data,
authentication on, generated PHOENIX_SECRET, PHOENIX_ADMIN_SECRET and
PHOENIX_DEFAULT_ADMIN_INITIAL_PASSWORD (kept only as that service's
variables), a public domain for the UI, and the service in the web service's
region. The web service gets PHOENIX_COLLECTOR_ENDPOINT (the private
http://phoenix.railway.internal:6006) and PHOENIX_API_KEY as a reference to
the admin secret, and every project worker gets references to those; nothing
is redeployed (workers take them on their next deploy). Each step checks first,
so restarts change nothing. bun run phoenix:provision does the same by hand.
Log in to the UI as admin@localhost with the password from the phoenix
service's variables. Phoenix's docs suggest replacing the admin secret with a
system API key once the instance is set up.
Locally: docker compose --profile tracing up -d phoenix, then set
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006 and open
http://localhost:6006. Project workers created by the provisioner inherit
these variables from the web service (on Railway as references to it).
Evaluating agents in Phoenix. bun run phoenix:evals uploads the dataset
spaces-agent-expectations (a passing and a failing output for each
expectation Spaces places on agent output: the verify, review, delivery and
dev-setup status lines and sections, question, task, plan and workstream
formats, no git commit/push from workstream agents, conventional commits,
JSON-only suggestions, no secrets in the clear) and runs the code checks of
src/lib/agent-evals.ts on it as an experiment; matches-expected shows the
checks agree with each sample's verdict. --traces 300 runs the same checks
on recent real agent outputs (dataset spaces-agent-turns, each example
linked to its span). --judges prints LLM-judge prompts for the rules that
need judgement, to add as evaluators in Phoenix's UI. Set
PHOENIX_COLLECTOR_ENDPOINT to the Phoenix URL and PHOENIX_API_KEY to a
system API key (Phoenix → Settings → API Keys).
Running the test suite¶
bun test runs a preload (tests/setup/db-guard.ts) that keeps the suite off
databases that are not test databases:
| Variable | Purpose |
|---|---|
TEST_DATABASE_URL |
Used as the suite's database when set |
DATABASE_URL |
Used only when it is local, or its database is named for tests (test, agent, ci) |
ALLOW_TEST_DATABASE |
1 accepts any DATABASE_URL (only for a disposable database) |
Anything else (a deployed application's database, such as Railway's railway)
makes the database suites skip with a message instead of writing to it.
Authentication and teams¶
| Variable | Default | Purpose |
|---|---|---|
AUTH_DISABLED |
unset | 1 turns sign-in off (single-user local use); every route is open |
SUPERADMIN_EMAILS |
unset | Comma-separated emails of the deployment's super admins, who manage the waitlist; when unset, the first registered account is the super admin |
SPACES_ROLE |
all |
all runs everything in one service. web is the public app with no workspace disk, forwarding project work to the project's worker. project is one project's worker (see specs/014-project-workers) |
SPACES_INTERNAL_TOKEN |
unset | Shared secret between the web service and project workers; required for web and project |
WORKER_PROJECT_ID |
unset | The project a project-role service serves |
PROJECT_WORKER_URL_TEMPLATE |
unset | web role: a project worker's address before provisioning records one, e.g. http://spaces-proj-{code}.railway.internal:3000 ({code}, {slug}, {projectId}) |
RAILWAY_PROVISIONER_TOKEN |
unset | Railway workspace token used to create and remove each project's worker service and volume (a project token can create but not delete); set it sealed, with RAILWAY_PROVISIONER_TOKEN_TYPE=workspace. Check it under the account menu → Project workers |
RAILWAY_PROVISIONER_TOKEN_TYPE |
project |
workspace or account if a broader token is used instead |
PROJECT_WORKER_VCPUS / PROJECT_WORKER_MEMORY_GB |
2 / 2 |
Size of each project worker |
PROJECT_WORKER_REPO |
rayedbajwa/spaces |
Repository project workers are built from; they have no branch or deployment trigger (only Spaces deploys them). Set it to your fork |
PROJECT_WORKER_PLATFORM |
Railway when RAILWAY_PROVISIONER_TOKEN is set |
railway, kubernetes or docker; every platform setting is in Project workers → Settings |
OPEN_REGISTRATION |
unset | 1 lets anyone register; otherwise only the first user, invitees and people let in from the waitlist can, and the landing page offers the waitlist |
DEFAULT_TEAM_NAME |
Default team |
Name of the team created for the first user |
DEFAULT_ORG_NAME |
Organization |
Name of the organization created for the first user |
GITHUB_SIGNIN_CLIENT_ID |
unset | Client id of the GitHub OAuth app used for "Continue with GitHub" |
GITHUB_SIGNIN_CLIENT_SECRET |
unset | Its client secret; both are needed or the button is not offered |
Sessions are HttpOnly cookies (30 days; Secure when served over HTTPS).
Signing in identifies a person to the whole deployment, so it uses its own
GitHub OAuth app from the two variables above, never an organization's
integration credentials. Register the app on GitHub with the callback
<your origin>/api/oauth/github/callback.
Integrations (OAuth)¶
Not configured through the environment. A team owner or admin sets each
provider app up under Organization → Integrations; credentials are
stored encrypted with ENCRYPTION_KEY. GitHub is created for you as a GitHub
App (manifest flow) and Slack from a prefilled manifest; Atlassian and Linear
are registered by hand with callback
http://<host>:<port>/api/oauth/<provider>/callback and these scopes (the
card shows them ready to copy). The GitHub scopes below only apply when a
classic OAuth App is pasted in; a GitHub App carries its permissions itself.
| Provider | Scopes |
|---|---|
| GitHub | repo, read:org, read:user |
| Atlassian (Jira + Confluence) | read:jira-user, read:jira-work, write:jira-work, read:confluence-content.all, read:confluence-content.summary, read:confluence-space.summary, search:confluence, write:confluence-content, offline_access — enable the same scopes on the app's Permissions page, and reconnect after adding any |
| Linear | read, write |
| Slack | channels:manage, channels:read, channels:join, chat:write, users:read, users:read.email, im:write |
Per-project settings (UI)¶
- Orchestrator (overview): autonomous mode (auto-approve gates), max concurrent runs, speed mode (fast / balanced / quality).
- Knowledge scope (Context tab): which integrations and repositories the project's agents may query, with Jira project keys, Linear teams/projects, Confluence spaces and GitHub repos.
- Repositories (overview): add, edit, make primary, relearn, retry clone.
Files agents write¶
| File | Written by | Purpose |
|---|---|---|
.aidlc/dev-setup.md |
dev-environment setup | Install/build/test/lint commands, test baseline, blockers (local-only) |
specs/<feature>/code-review.md |
review |
Review status and findings |
specs/<feature>/delivery-status.md |
before deliver/review |
PR, CI, merge, deploy state from GitHub |
specs/<feature>/delivery-report.md |
deliver |
Delivery status, UAT results, pending approvals |