Installation-level settings come from .env (deploy/compose/.env.example).
- Configured in the portal, not in
.env: Git servers, repositories, the commit identity ofkintsugi-bot(Settings → Git), the sandbox environment jobs run in (below), LLM providers, users and projects. - Configured per project in the document repo (
kintsugi.yaml).
| Variable | Required | Default | Description |
|---|---|---|---|
KINTSUGI_VERSION |
no | latest |
Image tag for kintsugi-app and kintsugi-worker; the worker also reports it in its heartbeat (Monitoring → Worker, ADR-0030), falling back to its package version when unset |
KINTSUGI_REGISTRY |
no | ghcr.io/evoelsewhere |
Container registry namespace hosting kintsugi-app and kintsugi-worker (use a local registry for air-gapped installs) |
KINTSUGI_HTTP_BIND |
no | 127.0.0.1 |
Host interface for the published app port. Loopback keeps the app private for SSH-tunnel access or a local TLS reverse proxy |
KINTSUGI_HTTP_PORT |
no | 8080 |
Published port of kintsugi-app |
KINTSUGI_PUBLIC_URL |
yes | http://localhost:8080 in the Compose starter |
External URL (used for links, MCP and CLI configuration); use the HTTPS URL when publishing behind a TLS reverse proxy |
KINTSUGI_RELEASES_DIR |
no | /app/releases in the image |
Folder of CLI packages the app serves at /api/v1/releases and lists in the Guideline (ADR-0070); the image build fills it |
KINTSUGI_SECRET_KEY |
yes | — | Master key encrypting secrets in Postgres (openssl rand -base64 32) |
KINTSUGI_BOOTSTRAP_ADMIN_USER |
yes (first start) | admin |
First admin account |
KINTSUGI_BOOTSTRAP_ADMIN_PASSWORD |
yes (first start) | — | First admin password; the deploy workflow accepts letters, digits, dots, underscores, and hyphens (minimum 8 characters). Change it after first sign-in |
POSTGRES_PASSWORD |
yes | — | Hexadecimal password of kintsugi, the Postgres bootstrap superuser (minimum 32 characters in the deploy workflow). Only the db-roles step and maintenance use it; the app and the worker never receive it |
POSTGRES_APP_PASSWORD |
yes | — | Hexadecimal password of kintsugi_app, the role the app and the worker connect as: no superuser, no CREATEDB or CREATEROLE, owner of the kintsugi database. The deploy workflow generates it when .env has none; the db-roles step sets it on every start |
KINTSUGI_DATA_DIR |
yes | <deployment directory>/data in the first Compose deployment |
Host directory for Git mirrors, document repo clones and per-job checkouts (ADR-0025); size it for every registered repository plus running jobs. Without Docker (development) it defaults to ./.kintsugi/data. The API reads the document repo mirrors here (read-only), so it needs the same value as the worker |
KINTSUGI_GIT_POLL_INTERVAL |
no | 180 |
Seconds between full Git re-syncs of every repository (minimum 30); new repositories are cloned within seconds |
KINTSUGI_TELEMETRY_RETENTION_DAYS |
no | 30 |
Days the spans of agent jobs (monitoring.telemetry_span) are kept (ADR-0048) |
KINTSUGI_WORKFLOW_CONCURRENCY |
no | 4 |
Agent jobs of one workflow running at a time |
KINTSUGI_STAGE_CONCURRENCY |
no | 4 |
Steps of one parallel or per-item group of a stage running at a time |
KINTSUGI_DEBUG_MCP |
no | unset | 1 on a development installation (set it for kintsugi-app and kintsugi-worker) serves the debug MCP server and mirrors the API's and the worker's logs to the database (ADR-0056). Never set it in production |
KINTSUGI_RUNTIME_MODE |
no | pi |
pi runs agent jobs with the configured LLM providers; mock runs them without an LLM (development and demos) |
KINTSUGI_PYTHON |
no | python3 (python on Windows) |
Python 3.12 interpreter for script steps and hooks |
KINTSUGI_NODE |
no | the worker's Node | Node 22+ interpreter for .js script steps |
KINTSUGI_JOB_UID, KINTSUGI_JOB_GID |
no | unset | Worker only, Linux: numeric user and group (never 0) that script steps, hooks and agent jobs run as, so they cannot read the worker's environment; the image has kintsugi-job (10002). Set both or neither: a half or malformed setting stops the worker; refused on Windows. Unset, jobs run as the worker's user and the worker logs a warning (ADR-0093). The Compose override docker-compose.isolated.yml sets both; probe-job-isolation.sh checks the boundary on the host |
Runtime jobs run in job workspaces under KINTSUGI_DATA_DIR/jobs/ without an OS-level sandbox (ADR-0029): run the worker as an unprivileged user (never root) whose only writable location is its data directory. Memory and CPU are bounded by the worker container, not per job.
The settings of the environment jobs run in are set by an administrator in Settings → Sandbox & Agent (permission sandbox.manage), stored in admin.installation_setting under sandbox, and read by the worker when a job starts and in each sweep: a change applies to the next job, without a restart (ADR-0055). They replace the variables KINTSUGI_JOB_DEFAULT_TIMEOUT, KINTSUGI_AGENT_IDLE_TIMEOUT, KINTSUGI_SCRIPT_TIMEOUT, KINTSUGI_JOB_MAX_OUTPUT_BYTES, KINTSUGI_JOB_MAX_TURNS, KINTSUGI_JOB_MAX_COST_USD, KINTSUGI_JOB_MAX_CONCURRENCY (now "Max job concurrency", followed while the worker runs) and KINTSUGI_JOB_RETENTION_DAYS, which the worker no longer reads.
| Setting | Default | Meaning |
|---|---|---|
| Keep the checkouts of a failed job (hours) | 24 |
After this long the sweep drops the checkouts and the documents of a failed or cancelled job; a retry makes them again from the pinned commits. 1 to 720 |
| Keep the results of a failed job (days) | 7 |
Days the workspace of a failed or cancelled run, or of a run whose document write failed, is kept for inspection and retries. Outputs whose document write is committed, opened as a pull request, merged, closed or unchanged are deleted at once. 1 to 90 |
| Script timeout (minutes) | 10 |
Wall-clock limit of a script step; the process tree is killed when it is exceeded. 10 seconds to 24 hours |
| Agent job timeout (minutes) | 45 |
Wall-clock limit of an agent job; 0 = no limit |
| Agent idle limit (minutes) | 5 |
No sign of life from the model (text, thinking, tool-call arguments, tool calls) for this long and the job is stopped as stalled and tried once more; 0 turns the watchdog off. A tool call that is still running counts as a sign of life for at most 11 minutes (longer than any kernel tool's own timeout), so a hung call is stopped too |
| Output limit (MB) | 50 |
What a step may write to its output and scratch folders together; a script step or an agent step that exceeds it is stopped (failure: output limit). 1 MB to 10 GB |
| Turns per agent job | 150 |
Assistant turns; 0 = no limit |
| Cost per agent job (USD) | 10 |
Model cost of the job, compaction summaries included; counted only for models whose prices are known. 0 = no limit |
| Mark checkouts and inputs read-only on disk | on | A second line of defence beside the kernel's path guard; switch it off where changing the permissions of thousands of files is slow |
Harness renderers and transformer plugins are configured in the portal (Admin → Harnesses). Runtime agents (built-in and custom) are managed in the Agent Builder and supplied per job (ADR-0026). The model binding per agent id is configured in the portal (Admin → LLM Providers).
| Variable | Container | Description |
|---|---|---|
DATABASE_URL |
app, worker | Postgres connection string, as kintsugi_app |