Documentation

Server config

Configure the API, worker, database, and sandbox environment.

On this page

Environment files

Compose reads the backend .env for variable substitution. The worker loads it through env_file. The API receives only its named variables and no model credentials. Compose clears database setup credentials from the worker environment.

Keep dashboard secrets in web/.env. Compose sets CROCODE_API_URL=http://api:8080. For local web development, use web/.env.local.

Existing databases need a one-time account setup before this upgrade. Follow the database upgrade steps. Keep the existing database volume.

The Rust binary reads environment variables at startup. It does not load .env itself. Compose runs crocode migrate before the API and worker start. Runtime services use a restricted database account.

Core settings

Variable	Default	Purpose
`DATABASE_URL`	Required	Restricted Postgres runtime account. Privileged roles are rejected.
`MIGRATION_DATABASE_URL`	Migration process only	Setup account for crocode migrate. Keep it out of runtime services.
`CROCODE_BIND`	0.0.0.0:8080	API listen address.
`CROCODE_CONFIG_DIR`	Unset	Directory containing github-app.json. Compose uses /config.
`GITHUB_APP_ID`	Required without setup	Numeric App ID. Enables environment-based GitHub settings.
`GITHUB_PRIVATE_KEY`	Required without a key path	App PEM key. Literal \n becomes a line break.
`GITHUB_PRIVATE_KEY_PATH`	Unset	PEM file path. Takes priority over the inline key. Unset it when unused.
`GITHUB_WEBHOOK_SECRET`	Required without setup	Webhook HMAC secret of at least 16 bytes.
`CROCODE_AGENTS`	claude,codex,opencode	Enabled agents. Compose and .env.example enable claude,opencode.
`CROCODE_DEFAULT_AGENT`	First enabled agent	Must appear in CROCODE_AGENTS.
`GITHUB_API_URL`	https://api.github.com	GitHub API base URL.
`GITHUB_WEB_URL`	https://github.com	Git host for repository checkout.

Worker and sandbox settings

Variable	Default	Purpose
`CROCODE_SANDBOX`	docker	Use none only for trusted local development.
`CROCODE_SANDBOX_IMAGE`	crocode-sandbox:latest	Image on the worker’s Docker daemon.
`CROCODE_SANDBOX_NETWORK`	bridge	Sandbox network. Does not create egress firewall rules.
`CROCODE_SANDBOX_RUNTIME`	Unset	Optional installed runtime, such as runsc.
`CROCODE_WORK_DIR`	/var/lib/crocode/work	Same absolute path on host and worker. Owner 10000:10000.
`CROCODE_WORKER_CONCURRENCY`	4	Worker slots per process. Minimum 1.
`CROCODE_MAX_PER_INSTALLATION`	2	Soft concurrency cap. Concurrent claims can exceed it.
`CROCODE_AGENT_TIMEOUT_SECS`	900	Agent timeout. Each Git command has a separate 300-second timeout.
`CROCODE_MAX_REPO_SIZE_MB`	1024	GitHub repository-size pre-check. This is not a disk quota.
`CROCODE_SAST`	on	Run OpenGrep static analysis before the agent. Set off to skip it.
`CROCODE_SAST_TIMEOUT_SECS`	300	Static analysis timeout.
`CROCODE_SAST_RULES`	/opt/opengrep-rules	Rules root. Change it only in host mode.
`CROCODE_AGENT_ENV`	Empty	Extra variable names passed to agents. Never include GitHub or dashboard secrets.
`CROCODE_LOG_FORMAT`	Plain text	Set json for JSON logs.
`RUST_LOG`	info	Tracing filter.

Queue behavior

A job can run up to three attempts. Retry delay starts at 30 seconds, doubles, and stops growing at ten minutes. The worker polls every two seconds and sends a heartbeat every 20 seconds.

The reaper checks every 60 seconds. It requeues jobs with heartbeats older than 120 seconds, or fails them when they reach the attempt limit. Delivery IDs expire after seven days.

These values are code constants. See the full configuration reference for Compose and retention details.

Weekly security digest

The weekly security digest is off by default. An installation admin turns it on in Settings with an HTTPS chat webhook URL. CroCode posts a Slack-compatible {"text": "..."} body. Slack and Mattermost accept it. For Discord, add /slack to the end of the webhook URL.

Every 7 days, the worker reads the Dependabot alerts of all installation repositories with a token that can only read alerts and metadata. The digest counts new alerts, fixed alerts, and open alerts past their deadline. It lists at most 5 alerts in each section.

Severity	Deadline
`critical`	15 days
`high`	30 days
`medium`	90 days
`low`	180 days

The message names repositories, packages, and CVE or GHSA IDs. It leaves GitHub. The database stores the webhook URL encrypted with a key derived from the GitHub App private key, and the API never returns it. After a private key rotation, enter the URL again. The worker sends only to public addresses on port 443 and follows no redirects. After a failed send it tries again every hour.