Environment variables

trackica reads environment variables at process startup. After changing one, restart the affected API, web, or daemon process. Docker Compose's docker compose restart does not re-read .env; recreate containers with up -d for changes to take effect.

This page lists deployment-facing configuration only; test variables and internal task variables are not covered here. It is a grouped reference — for full deployment steps, see the self-host quickstart.

Minimum production configuration

DATABASE_URL=postgres://user:password@postgres:5432/trackica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://trackica.example.com
TRACKICA_APP_URL=https://trackica.example.com
TRACKICA_PUBLIC_URL=https://api.trackica.example.com

You also need to pick an email service, otherwise verification codes and invitations are only written to the server log.

API and database

When setting a shutdown hold on Kubernetes, terminationGracePeriodSeconds must exceed the hold plus the time the actual shutdown needs.

Public URLs and browser access

When the frontend and API run on different hosts and the browser talks to the API domain directly, you must set COOKIE_DOMAIN — otherwise the browser cannot read the CSRF cookie: every write request returns 403 CSRF validation failed while reads work fine. Use the narrowest parent domain that covers both hosts (.agent.example.com over .example.com). It spreads the sign-in session cookie to every host under that domain, which is only acceptable when all of those hosts are operated by the same trusted party. After changing it, clear the old cookies on both hosts and sign in again. If you follow the same-origin recipe in the self-host quickstart (the browser only visits the app domain), keep it empty. Do not use an IP address — browsers ignore cookies whose Domain is an IP.

Email and sign-in

Resend

SMTP

SMTP takes priority over Resend whenever SMTP_HOST is non-empty.

Google OAuth

Signup scope

For the exact allowlist evaluation order, see Sign-in and signup.

Attachment storage

When S3_BUCKET is unset, trackica uses local disk.

S3 or compatible storage

Use ATTACHMENT_DOWNLOAD_MODE=proxy when the endpoint — an internal MinIO, for example — is not reachable from the browser.

Local disk

CloudFront

Redis and rate limiting

Deployments behind a reverse proxy must list their real proxy ranges. Do not blanket-trust all sources, or clients can forge forwarded IPs.

The auth rate limits require REDIS_URL; without it, the startup log notes that auth rate limiting is disabled. Invitation limits still run in process-local memory without Redis and become shared across replicas when Redis is configured. If configured Redis becomes temporarily unavailable, auth rate limiting fails open, while invitation creation returns a retryable 503 instead of sending email without protection.

External integrations

Without GITHUB_APP_ID and the private key, PRs still link, mirror, and trigger merge-to-done normally, but cards show no CI or mergeability status, and the "pick from GitHub" repository entry is disabled.

For setup steps, see GitHub integration, Lark bot, Slack bot, and Telegram bot.

Server-side LLM

This group configures server-side assist generation, such as conversation titles; it is not the AI coding tool credentials agents use to execute tasks.

TRACKICA_LLM_MAX_RETRIES is the single source for the retry policy. Leave it unset for the default of 2, set 0 to send exactly one request per call, or set 1–5 to cap retries at that many. It is a ceiling, not a quota: only retryable failures consume it, and a success or the caller's own deadline can end the call sooner. Any other value — negative, non-numeric, or above 5 — fails startup instead of being corrected silently. The ceiling is a latency budget: backoff starts at 0.5s and doubles to an 8s cap, so a larger budget would outlast the callers' own deadlines and turn a retryable failure into a timeout. Retries cover connection failures and HTTP 408, 409, 429 and 5xx; all other 4xx responses are returned as-is. The server logs the effective policy at startup as llm retry policy, with no credentials in the line.

Four features use this layer and send the following data to the endpoint you configure:

• Chat auto-titling — the first user message of a new chat session, sent verbatim. Attachments are never included.
• Follow-up questions (the suggestion buttons under an agent reply) — the tail of the conversation: up to 6 messages, with the reply being answered capped at 3000 characters and each older message at 800.
• Gantt status summaries — up to 100 user-selected issues, including identifier, title, description (up to 2000 characters), status, priority, dates, and project title.
• Project snapshot summaries — structured project facts: status, ownership, milestones, tasks, deliveries, repository checks, progress, health signals, and risk flags. Issue descriptions, comments, attachments, and chat are not included. When both the API key and the base URL are empty, this layer is disabled and makes no upstream request at all — none of the features above sends anything. That is the supported configuration when your policy does not allow this layer to send data off the deployment: chat sessions keep the title the client derives from the first message, follow-up question buttons and AI Gantt summaries do not appear, and project snapshots retain their factual fallback.

Daemon configuration

The variables below are read on the computer that runs your agents, not in the API container.

Each AI coding tool accepts TRACKICA_<PROVIDER>_PATH and TRACKICA_<PROVIDER>_MODEL to override the command path and default model. QwenPaw and MiniMax Code have no model variable because trackica never sends them a model; MiniMax Code's path variable is TRACKICA_MCODE_PATH — see AI coding tools comparison. DeepSeek Harness supports TRACKICA_DSH_PATH and TRACKICA_DSH_MODEL (a model id from the dsh catalog, e.g. deepseek-official/deepseek-chat). Dim supports TRACKICA_DIM_PATH and TRACKICA_DIM_MODEL (a model id from the dim catalog). ZeroClaw supports TRACKICA_ZEROCLAW_PATH but has no model variable; its agent profile owns the model selection. Machine-wide default arguments via TRACKICA_<PROVIDER>_ARGS are currently supported for five tools: Claude Code, Codex, CodeBuddy, Qwen Code, and QwenPaw. The variables are TRACKICA_CLAUDE_ARGS, TRACKICA_CODEX_ARGS, TRACKICA_CODEBUDDY_ARGS, TRACKICA_QWEN_ARGS, and TRACKICA_QWENPAW_ARGS. For example:

TRACKICA_CLAUDE_PATH=/opt/bin/claude
TRACKICA_CLAUDE_ARGS=--max-turns 40

Precedence is command-line flag → environment variable → ~/.trackica/config.json → built-in default. For watchdog behavior, see Daemon and runtimes.

Persisting daemon configuration

Common daemon-side settings can also be written to ~/.trackica/config.json instead of relying on shell environment variables; named profiles keep theirs at ~/.trackica/profiles/<name>/config.json:

trackica config set poll_interval 10s
trackica config show

Supported keys:

A few value rules:

• Duration keys accept positive Go durations (such as 10s, 2h); 0s and negative values are rejected. The one exception is agent_timeout: 0s is valid and explicitly disables the run time limit.
• Passing an empty string clears a persisted value and falls back to the env var or built-in default, for example trackica config set poll_interval "".
• max_concurrent_tasks requires a non-negative integer.
• Relative workspaces_root values are converted to absolute paths when saved.

Observability and analytics

Next steps

• Sign-in and signup — sign-in methods and signup restrictions.
• Troubleshooting — symptom-based diagnosis of deployment problems.
• Daemon and runtimes — the daemon-side counterparts of this configuration.