Environment Variables

All Crewship configuration can be set via environment variables. These override values from the YAML config file. The mapping is defined in applyEnvOverrides in internal/config/config.go.

As of PR #446, no env vars are required for first boot — secrets are auto-generated and persisted. Set variables here only to override a default or hand a secret to an external manager. Jump to a group: Server · Container · Storage · Auth · Encryption · Keeper · CLI client · Installer.

Server

Variable	Default	Description
`CREWSHIP_HOST`	`0.0.0.0`	Server listen address
`CREWSHIP_PORT`	`8080`	Server listen port

IPC

Variable	Default	Description
`CREWSHIP_SOCKET_PATH`	`<data dir>/crewship.sock` — `/tmp/crewship.sock` for the packaged install	Unix socket path for internal IPC. The socket follows the resolved data dir, which is `CREWSHIP_DATA_DIR` when set and `$HOME/.crewship` when it is not. The `/tmp/crewship.sock` literal survives for exactly one case: a data dir of `/var/lib/crewship`, which is what the deb/rpm unit pins — so a packaged install keeps the path it has always had, and two instances anywhere else get their own. If the derived path would exceed the ~100-byte `sockaddr_un` limit, the default falls back to `<tmpdir>/crewship-<hash-of-data-dir>.sock`, hashed so the fallback is still per-instance. Starting the server refuses outright if something is already listening on the socket path, rather than unlinking a running instance’s socket.

Container

Variable	Default	Description
`CREWSHIP_CONTAINER_PROVIDER`	`docker`	Container provider: `docker`, `apple`, `auto` (Kubernetes provider on the v0.2 roadmap)
`CREWSHIP_RUNTIME`	(unset — uses `container.default_runtime`, else `runc`)	Overrides the OCI runtime handed to Docker for crew containers (`runc`, `runsc`, `kata-runtime`, `sysbox-runc`). Wins over the YAML `container.default_runtime`. Read by `internal/provider/docker/docker_container.go`.
`CREWSHIP_CONTAINER_NETWORK`	`crewship-agents`	Docker bridge network name
`CREWSHIP_CONTAINER_PREFIX`	(empty)	Container name prefix for multi-instance isolation
`CREWSHIP_RUNTIME_IMAGE`	`debian:bookworm-slim`	Default agent runtime image for crews without an explicit `runtime_image`. Any glibc-based Linux image works — Crewship bind-mounts the sidecar and entrypoint at runtime.
`CREWSHIP_SIDECAR_ENABLED`	`false`	Enable sidecar proxy (`true` or `1`)
`CREWSHIP_SIDECAR_PATH`	autodetected	Absolute host path to the `crewship-sidecar` Go binary. See Devcontainers reference for autodetect order.
`CREWSHIP_ENTRYPOINT_PATH`	autodetected	Absolute host path to `entrypoint.sh`.
`CREWSHIP_SKIP_SIDECAR`	(unset)	Set to `1` to bypass fail-fast autodetect (tests only — never set in production).
`CREWSHIP_ALLOW_STALE_RUNTIME_IMAGE`	(unset — fail closed)	Set to `1`/`true` to let a crew container start from a known-stale local image — whether the registry pull failed or the pull succeeded but the local tag could not be moved onto it. See Runtime image pinning below.

Runtime image pinning

Before starting a crew container, Crewship resolves the runtime image tag to an OCI manifest digest (a registry HEAD) and then pulls that digest, not the tag. A tag can be repointed between the check and the fetch; a digest cannot. The digest is recorded on the crew’s provisioning.step journal entry (payload.digest, plus payload.pinned), stamped with the run’s trace_id, so the audit trail can answer which image produced this run. Read it back with:

# every image a crew has started from
crewship journal --type provisioning.step --crew <slug>

# the image one specific run executed under
crewship journal --type provisioning.step --trace-id <run-id>

No new endpoint or command was needed for this — the digest rides the existing provisioning.step payload, which crewship journal already returns. Offline and air-gapped installs are unaffected. When the registry cannot be reached at all, the digest lookup returns nothing and Crewship keeps using the local copy exactly as before — it just logs the local digest alongside, so even an offline run is attributable. When the local image is provably stale. This is the case that changed. Two different failures land a host in the same state — the registry answered the digest check, and the tag the container will start from resolves to a different manifest. That is provable drift, not a guess, so Crewship refuses to start the container rather than silently running the wrong image. CREWSHIP_ALLOW_STALE_RUNTIME_IMAGE=1 is the single host-wide opt-out for both routes. Route 1 — the pull failed. Reaching a pull with a local copy present means the digest check succeeded and the local copy did not match it:

runtime image ghcr.io/example/runtime:latest is known-stale: the registry pull
failed: toomanyrequests: rate limit exceeded; ghcr.io/example/runtime:latest
resolves to sha256:bbbb… on this host while the registry names sha256:aaaa…;
refusing to start a crew on an image the registry contradicts — re-run once the
registry accepts the pull again (a rate limit clears on its own), or set
CREWSHIP_ALLOW_STALE_RUNTIME_IMAGE=1 to accept the stale copy host-wide

The most common cause is a registry rate limit (Docker Hub answers HEAD generously and throttles blob pulls). Route 2 — the pull succeeded but the tag could not be moved. A digest-pinned pull leaves the image on disk unnamed, so Crewship re-creates the repo:tag alias itself. If the daemon refuses that and an older copy of the tag is still there, the tag keeps pointing at the old manifest and every downstream lookup — ContainerCreate included — addresses the image by tag. Crewship re-reads the tag before deciding, and refuses on the same terms:

runtime image ghcr.io/example/runtime:latest is known-stale: the pull succeeded
but the local tag could not be moved onto the pulled manifest: conflict: cannot
restore tag; ghcr.io/example/runtime:latest resolves to sha256:bbbb… on this
host while the registry names sha256:aaaa…; refusing to start a crew on an
image the registry contradicts — the pulled manifest is already on disk, name
it with `docker tag ghcr.io/example/runtime@sha256:aaaa…
ghcr.io/example/runtime:latest`, or re-run once the daemon accepts the re-tag,
or set CREWSHIP_ALLOW_STALE_RUNTIME_IMAGE=1 to accept the stale copy host-wide

This route is the more recoverable of the two: the manifest you wanted is already on disk, it just has no name, which is why the error hands you the docker tag that fixes it properly. Digests are abbreviated (sha256:aaaa…) in the examples above for width — the real error prints them in full, and the docker tag line it gives you is runnable as printed. What the opt-out does and does not relax. With CREWSHIP_ALLOW_STALE_RUNTIME_IMAGE=1 both routes proceed, log a warning naming both digests, and journal the local digest — what actually ran — with payload.pinned: false. The escape hatch relaxes execution only. It never relaxes the audit record: a provisioning.step row never claims a digest that did not run, opt-out or not. One case is deliberately left alone: if the re-tag fails and the daemon answers 404 for the tag afterward, there is no stale image to run and no digest to record. The provisioning.step row is still written — it just carries no digest and pinned: false — and the daemon’s own error surfaces at container create, which is where it is most legible. A read-back that fails rather than answering 404 is not the same thing and is not treated as one: a timeout or a busy daemon says nothing about what the tag resolves to, so Crewship falls back on what it proved before the pull. If a local copy was present then (which is what sent it to the pull in the first place), the tag is still the stale one and the start is refused. Locally built devcontainer cache images (crewship-cache:*) exist in no registry and therefore have no digest. Their provisioning.step rows omit the digest key entirely; their provenance is the base image recorded on the build’s own steps.

Set by Crewship inside the container

These are not configuration — Crewship sets them on the crew container itself, and an agent (or a postCreateCommand) can read them.

Variable	Description
`CREWSHIP_CREW_ID`	The crew’s id. Set on every crew container by both providers, and the one variable the Apple provider guarantees regardless of what the devcontainer’s own `containerEnv` asks for. Useful for a hook or script that needs to know which crew it is running in.

CREWSHIP_CONTAINER_PREFIX is essential for multi-instance deployments. Without it, multiple Crewship instances will create containers with colliding names like crewship-team-engineering.

Storage

Variable	Default	Description
`CREWSHIP_DATA_DIR`	`~/.crewship`	Root directory for `crewship.db`, output, chats, logs, skills, and workspace memory. Resolved by `database.DefaultDataDir` — every admin / backup / doctor / start path flows through it.
`DATABASE_URL`	(unset)	Direct DSN override for `crewship admin` only. Bypasses `CREWSHIP_DATA_DIR` resolution. Use when running admin commands against a SQLite file outside the standard data-dir tree.
`CREWSHIP_STORAGE_PROVIDER`	`localfs`	Storage backend. `localfs` is the only implemented provider; any other value is refused at startup rather than accepted and ignored.
`CREWSHIP_STORAGE_BASE_PATH`	`/var/lib/crewship`	Base path for local file storage
`CREWSHIP_STORAGE_MEMORY_ROOT`	(unset)	Parent directory for the workspace memory tier. Unset disables that tier and memory versioning. `crewship start` derives it from the data directory, but only when `DATABASE_URL` is unset — set this explicitly in any deployment that brings its own database
`CREWSHIP_LOG_PATH`	`/var/log/crewship`	Path for log files

State

Variable	Default	Description
`CREWSHIP_STATE_PROVIDER`	`bbolt`	State store: `bbolt` (postgres on the v0.2 roadmap)
`CREWSHIP_BOLT_PATH`	`<data dir>/state.db` — `/var/lib/crewship/state.db` for the packaged install	BoltDB file path. Same rule as `CREWSHIP_SOCKET_PATH`: it follows the resolved data dir, which is `CREWSHIP_DATA_DIR` when set and `$HOME/.crewship` when it is not, so the `/var/lib/crewship` literal is the default only for the packaged install. The bbolt file is exclusively locked by whichever process opens it, so instances must not share one.

Public-facing URL

Variable	Default	Description
`CREWSHIP_PUBLIC_URL`	(unset)	Externally-reachable base URL of the Crewship server. Required for password-recovery emails and for `/expose-port` (port-exposed agent containers). Without it the recovery email link is degraded and `/expose-port` returns `503` with a `CREWSHIP_PUBLIC_URL not set` log line.
`CREWSHIP_PAGES_EMBED_SOURCES`	(unset)	Comma-separated `name=https://url` pairs a human has vetted as embeddable in a Pages `embed.v1` panel. Unset means embed panels are disabled and a page spec cannot declare one. A payload names one of these names, never a URL — the URL is resolved server-side on read, so nothing a producer pushes can point a reader’s browser somewhere new. One malformed entry refuses the whole list rather than being skipped; only `https` is accepted, and a source resolving to this instance’s own origin is refused.

Origin enforcement (CORS / EnforceOrigin)

Variable	Default	Description
`CREWSHIP_ALLOWED_ORIGINS`	(unset — same-origin only)	Comma-separated allowlist of cross-origin `scheme://host[:port]` values that may issue state-changing requests (POST/PUT/PATCH/DELETE). Parsed by `internal/api/origin_check.go`; matched as exact host equality after `url.Parse` (no suffix wildcards, no IDN tricks — those previously enabled bypasses). The same allowlist now also governs WebSocket upgrade origins (`internal/ws/hub.go`) — required for desktop shells, whose webviews present a custom origin (Tauri: `tauri://localhost` on macOS, `http://tauri.localhost` on Windows/Linux). Required whenever the frontend is served from a different origin than the daemon (cross-origin Playwright E2E, separate `:3001` dev frontend on `nuke`-reset envs, reverse-proxy host with custom domain). `dev.sh` writes this automatically alongside `NEXTAUTH_URL`/`CREWSHIP_PORT` so the value survives `./dev.sh nuke`. Example: `CREWSHIP_ALLOWED_ORIGINS=https://app.crewship.io,https://staging.crewship.io`.

Rate limiting & proxy trust

Variable	Default	Description
`CREWSHIP_TRUSTED_PROXY_CIDRS`	(unset — only loopback `127.0.0.0/8` and `::1/128` trusted)	Comma-separated list of CIDR ranges whose `X-Forwarded-For` header the rate limiter and client-IP extractor will trust. Set this to the address(es) of your reverse proxy (nginx/Caddy/load balancer) so per-IP throttles see the real client IP. Leaving it unset means any non-loopback client presenting a forged `X-Forwarded-For` is ignored (the header is only honoured from trusted hops). Read by `internal/api/ratelimit.go`.
`CREWSHIP_ENV`	(unset — treated as non-prod)	Deployment environment label. When set to `prod` or `production` (case-insensitive), the server refuses to start if rate limiting has been disabled, and tightens WebSocket origin enforcement. Any other value (or unset) is treated as non-production. Read by `internal/api/ratelimit.go` and `internal/ws/hub.go`.
`CREWSHIP_RATELIMIT_DISABLED`	(unset — limiter on)	Dev only. Set truthy to disable the per-IP rate limiter. Ignored in production — when `CREWSHIP_ENV=prod`/`production` the limiter always runs regardless of this flag. Legacy alias `CREWSHIP_DISABLE_RATELIMIT` is also honoured. Read by `internal/api/ratelimit.go`.
`CREWSHIP_INTERNAL_ALLOW_ANY`	(unset — network gate on)	Dev only. When set to the literal string `true` (strict equality — `1`/`yes` are ignored), disables the internal-IPC network gate so `X-Internal-Token` becomes the sole guard on `/api/v1/internal/*`. Only safe behind a trusted reverse proxy. Read by `internal/api/internal.go`.
`CREWSHIP_INTERNAL_TRUSTED_PROXIES`	(unset — gate on the direct peer only)	Comma-separated CIDRs / IPs of reverse proxies allowed to front `/api/v1/internal/` (#1020). When the direct peer matches, crewshipd resolves the real client from the rightmost untrusted* `X-Forwarded-For` hop (or `X-Real-IP` if no XFF) and applies the origin gate to it; a present-but-unusable header is refused (fail-closed). Honored only for a trusted-peer connection (direct clients can’t spoof it), never auto-includes private ranges, and rejects an all-zeros CIDR (`0.0.0.0/0`); configured ranges are logged at startup. Your proxy MUST forward `X-Forwarded-For` or `X-Real-IP` — if it forwards neither the gate falls back to the proxy IP (fail-open). Distinct from `CREWSHIP_TRUSTED_PROXY_CIDRS` (rate-limiter attribution). Prefer not proxying the internal surface at all — see the internal API reference. Read by `internal/api/internal.go`.

Metrics

Variable	Default	Description
`CREWSHIP_METRICS_TOKEN`	(unset — metrics only reachable from loopback)	Bearer token gating non-loopback access to the Prometheus `/metrics` endpoint. Loopback peers are always allowed; remote scrapers must send `Authorization: Bearer <token>`. When unset, non-loopback requests are rejected outright. Read by `internal/server/routes.go`.

Webhooks / hooks (SSRF guard)

Variable	Default	Description
`CREWSHIP_HOOKS_ALLOW_PRIVATE`	(unset — private destinations blocked)	Set to `1`/`true`/`yes`/`on` to allow hook/webhook handlers to dial loopback and RFC1918 private addresses. Off by default so a misconfigured hook cannot reach localhost services or internal LAN hosts. Link-local (cloud metadata IMDS `169.254.169.254`), multicast, and unspecified addresses stay blocked regardless of this flag. Read by `internal/hooks/http.go`.
`CREWSHIP_ALLOW_PRIVATE_ENDPOINTS`	(unset — private endpoints blocked)	Instance-level ceiling for BYO model endpoints reaching private networks. A crew’s per-crew `allow_private_endpoints` opt-in only takes effect when this is also set to `1`/`true`/`yes`/`on`, so on a shared or cloud host a workspace admin cannot self-grant RFC1918/loopback egress by flipping the crew flag alone. Also gates daemon-side OLLAMA model discovery (`GET /api/v1/models` + set-time model validation): the daemon will only dial a workspace `ENDPOINT_URL` that resolves to a private/loopback address when this is set; link-local/metadata addresses stay hard-blocked regardless. Read by `internal/orchestrator` (`effectiveAllowPrivateEndpoints`) and `internal/api` (`ollamaDiscoveryClient`).

Profiling & observability

These are off by default and intended for operators debugging performance.

Variable	Default	Description
`CREWSHIP_PPROF_ADDR`	(unset — pprof disabled)	Bind address for the Go `net/http/pprof` server (recommended: `127.0.0.1:6060`, loopback only). Exposing pprof publicly is an info-leak and DoS vector, so it stays off unless explicitly set. Read by `internal/server/server.go`.
`CREWSHIP_PYROSCOPE_URL`	(unset — push profiling disabled)	Pyroscope server URL. When set, the binary continuously pushes CPU/heap/goroutine/alloc profiles. Read by `internal/server/server.go`.
`CREWSHIP_PYROSCOPE_TAG_SLOT`	(hostname)	Value for the `slot` tag attached to Pyroscope profiles, used to filter the Grafana flame-graph per dev slot/instance. Falls back to the machine hostname when unset. Read by `internal/telemetry/pyroscope.go`.
`OTEL_EXPORTER_OTLP_ENDPOINT`	(unset — noop tracer)	Standard OpenTelemetry OTLP HTTP base endpoint for GenAI traces; `/v1/traces` is appended, including to a project-scoped prefix. When unset, tracing silently degrades to a no-op tracer so local dev runs without an observability stack. Read by `internal/server/server.go` / `internal/telemetry/provider.go`.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	(unset)	The full trace URL, used exactly as written and taking precedence over the base endpoint. Use it when the collector serves traces off a non-standard path. Read by `internal/telemetry/provider.go`.
`CREWSHIP_SERVICE_NAME`	`crewshipd`	Overrides the OpenTelemetry `service.name` resource attribute. Set per binary (e.g. `crewship-sidecar`) or per tenant to differentiate traces. Read by `internal/telemetry/service_name.go`.

Crash reporting (Sentry)

Variable	Default	Description
`CREWSHIP_SENTRY_DSN`	(vendor default, baked-in at build time)	Operator override for the crash-reporting DSN. Empty string disables crash reporting at startup even when telemetry consent is on. Read by `internal/crashreport/crashreport.go`.

Email (password recovery)

Variable	Default	Description
`RESEND_API_KEY`	(unset — recovery emails disabled)	Resend API key for transactional email delivery. When unset, password-recovery flows surface a “configure RESEND_API_KEY or share the reset link manually” message instead of sending.
`RESEND_FROM`	(unset — required together with API key)	`From:` address used for outbound recovery emails (e.g. `Crewship <recovery@example.com>`).

Variable	Default	Description
`GOOGLE_CLIENT_ID`	(unset — Google sign-in disabled)	OAuth 2.0 client ID for the “Sign in with Google” flow. Loaded via `applyEnvOverrides` in `internal/config/config.go`.
`GOOGLE_CLIENT_SECRET`	(unset)	OAuth client secret paired with the client ID. Required when `GOOGLE_CLIENT_ID` is set.

Logging

Variable	Default	Description
`CREWSHIP_LOG_LEVEL`	`info`	Log level: `debug`, `info`, `warn`, `error`
`CREWSHIP_LOG_FORMAT`	`json`	Log format: `json` or `text`

CLI and runtime context

These names are used by CLI commands, test harnesses, or the agent runtime rather than by the server’s main YAML configuration. They are listed here so a deployment or script can distinguish an intentional context variable from a typo.

Variable	Default	Description
`CREWSHIP_CHAT_ID`	(unset)	Chat/session identifier supplied to a command that resumes or inspects one conversation.
`CREWSHIP_CREW_SHARED`	(unset)	Runtime marker selecting the crew-shared memory or filesystem context.
`CREWSHIP_E2E_SKIP_TOKEN_PROBE`	(unset)	Test-only switch that skips the end-to-end token probe when a harness target cannot support it.
`CREWSHIP_INPUT`	(unset)	Input value passed to a CLI or routine step that accepts an environment-backed input.
`CREWSHIP_INPUT_PERIOD`	(unset)	Input period used by recurring routine fixtures and schedule tests.
`CREWSHIP_MEMORY_SCRUBBER_MODE`	(unset)	Runtime memory-scrubber mode used when exercising memory redaction behaviour.
`CREWSHIP_MEMORY_WATCHER`	(unset)	Enables the development memory watcher used by local runtime tooling.
`CREWSHIP_OUTPUT_DIR`	(unset)	Output directory override for a local command or harness run.
`CREWSHIP_SECRETS_DIR`	(unset)	Directory override for runtime secret files in local or test environments.
`CREWSHIP_TOOL_NAME`	(unset)	Tool name carried in agent execution context and diagnostics.
`CREWSHIP_VAR`	(unset)	Generic fixture variable used by command and routine tests.
`CREWSHIP_WORKSPACE_ID`	(unset)	Explicit workspace identifier for a CLI or harness operation when the profile has no default workspace.

Authentication

Variable	Default	Description
`NEXTAUTH_SECRET`	Auto-generated on first boot	JWT signing secret for user authentication. Generated via `crypto/rand` (32 bytes → 64 hex chars) and persisted to `<dataDir>/secrets.env` on first start; subsequent boots read the file back. Explicit env vars always win, so Vault / Kubernetes secret mounts / `EnvironmentFile=` keep working unchanged.
`CREWSHIP_NEXTJS_URL`	Auto-derived from port	Internal URL for self-referencing API calls
`CREWSHIP_INTERNAL_TOKEN`	Auto-generated per boot	Token for sidecar-to-crewshipd IPC authentication. Generated fresh with `crypto/rand` on every start when unset (`internal/config/config.go`) — it is not part of the persisted `secrets.env` bootstrap, so it rotates on each restart. That is fine for single-binary mode (the sidecar receives the current token when it is spawned). Pin an explicit value only when multiple instances must share one IPC bus.
`CREWSHIP_ADMIN_TOKEN_HMAC_KEY`	Auto-generated on first boot	256-bit hex HMAC key for hashing ADMIN-tier CLI tokens at rest (`cli_tokens` table). Kept separate from `ENCRYPTION_KEY` so a DB dump alone cannot offline-crack admin tokens. Bootstrapped + persisted to `<dataDir>/secrets.env` like `ENCRYPTION_KEY` (32 bytes → 64 hex chars), so the ADMIN tier works out of the box. Read via `internal/secrets/bootstrap.go`.
`CREWSHIP_FORCE_SECURE_COOKIES`	(unset — off)	Set truthy to force the `Secure` flag on auth cookies even when the `X-Forwarded-Proto` header is dropped by a proxy. Set behind any HTTPS edge. Read by `internal/api/nextauth.go`.
`CREWSHIP_ALLOW_SIGNUP`	`false`	Allow new user registration (`true` or `1`)
`CREWSHIP_BOOTSTRAP_WINDOW`	(unset — open until first admin)	Opt-in finite first-run window. Unset (default), `/bootstrap` stays open until the first admin account exists (the empty user table is the gate). Set to a positive Go duration (e.g. `5m`, `30s`, `1h`) to arm a deploy-race window that refuses `/bootstrap` with `410` after it elapses — for instances exposed to the internet before they’re bootstrapped. Invalid or non-positive values are ignored (falls back to the open-until-admin default).

As of PR #446 (internal/secrets), the three persisted secrets — ENCRYPTION_KEY, NEXTAUTH_SECRET, and CREWSHIP_ADMIN_TOKEN_HMAC_KEY (the managed list in internal/secrets/bootstrap.go) — are bootstrapped on first start: missing values are generated with crypto/rand, persisted atomically to <dataDir>/secrets.env at mode 0600, and re-exported into the process environment so existing os.Getenv call sites see them unchanged. Explicit env vars override the file; partial persistence is handled (one missing key is filled, the other valid keys are preserved). CREWSHIP_INTERNAL_TOKEN is handled separately — the config loader generates it per boot when unset and does not persist it, so it rotates on each restart. For clustered deployments, set all four explicitly via your secret manager.

Auto-Derived Values

CREWSHIP_NEXTJS_URL: If not explicitly set, defaults to http://localhost:{CREWSHIP_PORT}. In single-binary mode, the internal resolver calls itself on the same port.
CREWSHIP_INTERNAL_TOKEN: Generated fresh per boot by the config loader when unset; not persisted, so it rotates on restart. Pin it explicitly only for multi-instance IPC bus sharing.

Encryption

Variable	Default	Description
`ENCRYPTION_KEY`	Auto-generated on first boot	256-bit hex-encoded AES key for credential encryption. Same auto-gen + persist path as `NEXTAUTH_SECRET` (32 bytes → 64 hex chars in `<dataDir>/secrets.env`).
`ENCRYPTION_KEY_V2`	(optional)	Rotated encryption key (for key versioning)
`CREWSHIP_ALLOW_PLAINTEXT_SECRETS`	`false`	Escape hatch — leave unset. Secret writes fail closed: with no usable encryption key, Crewship refuses to store the secret instead of writing plaintext. Setting this to `true` (or `1`/`yes`/`on`) restores the legacy plaintext-on-no-key behaviour, logging a `WARN` on every unprotected write. See Encryption → No key configured.

Composio integrations

Variable	Default	Description
`COMPOSIO_API_KEY`	(unset — provider off)	Server-wide Composio project API key (`ak_…`). When set, auto-enables the Composio provider unless `COMPOSIO_ENABLED` is explicitly set. Fallback when a workspace has no per-workspace key. Single-tenant: one key = one Composio project shared by all workspaces.
`COMPOSIO_ENABLED`	(derived from `COMPOSIO_API_KEY`)	Gates only the server-env path (`true`/`1` … `false`/`0`): it forces the env-key auto-enable on without a key, or off so a present `COMPOSIO_API_KEY` is ignored. It is not a global kill switch — a workspace that has saved its own key (`composio_settings`) keeps Composio regardless, since the per-workspace key takes precedence over the env fallback.
`COMPOSIO_BASE_URL`	(Composio production host)	Override the Composio API host (self-host / proxy / testing).
`COMPOSIO_DEFAULT_CONNECTOR`	`false`	When `true`/`1`, every agent without an explicit per-agent Composio binding inherits a workspace-wide default connector (full access to all connected apps), and legacy non-Composio MCP servers are excluded at resolve time. Behaviour switch only — never auto-enables the provider.
`NEXT_PUBLIC_LEGACY_MCP_INTEGRATIONS`	(unset)	Build-time dashboard flag. `=true` restores the legacy self-hosted MCP integrations UI at `/integrations` (default is the managed Composio UI).

Keeper (AI Security Gatekeeper)

Variable	Default	Description
`KEEPER_ENABLED`	`false`	Enable Keeper AI gatekeeper (`true` or `1`)
`KEEPER_OLLAMA_URL`	`http://localhost:11434`	Endpoint any `ollama` provider row resolves to — the Keeper judge and every auxiliary slot set to `ollama`. It is `ProviderSpec.BaseEnv` for that row (`internal/llm/registry.go`), not a Keeper-only variable.
`KEEPER_MODEL`	(none)	Model for Keeper evaluations (e.g. `claude-haiku-4-5`, or an Ollama model name). No default — an enabled Keeper with an empty model fails startup validation.
`ANTHROPIC_API_KEY`	(none)	*Required when `KEEPER_MODEL` (or an auxiliary-model slot) names a `claude-` model** — the server builds an Anthropic provider for it and an empty key is a hard error / `503`. Not needed for Ollama models.
`OPENAI_API_KEY`	(none)	Required when an auxiliary-model slot names the `openai` provider — the server’s own OpenAI key. Same rule as `ANTHROPIC_API_KEY`: an empty key is a hard error rather than a provider that 401s on first use. These two are `ProviderSpec.KeyEnv` for their registry rows, and which one an unconfigured instance defaults to depends on which you have set — see Multi-provider LLM configuration. Distinct from the same-named variable injected into an agent container (`crewship credential`); this one is the server’s.

Setting KEEPER_OLLAMA_URL auto-enables Keeper (unless KEEPER_ENABLED is explicitly false). This means you only need to set the URL to activate Keeper.

Local models (coding agents)

Variable	Default	Description
`CREWSHIP_LOCAL_MODEL_BASE_URL`	(none — disabled)	OpenAI-compatible endpoint (Ollama, LM Studio, llama.cpp) for agents using `ollama/…` models via the OpenCode adapter. Must be reachable from inside crew containers, e.g. `http://host.docker.internal:11434/v1`. Distinct from `KEEPER_OLLAMA_URL`, which serves the daemon’s internal Keeper layer. See CLI adapters → Local models.

LLM Proxy

Variable	Default	Description
(YAML only)	`llm_proxy.enabled: true`	Enable LLM proxy
(YAML only)	`llm_proxy.token_sync_interval: 30s`	Token sync interval
(YAML only)	`llm_proxy.health_check_interval: 60s`	Health check interval

Paymaster (Billing Modes)

These variables tag every cost-ledger row written from inside an agent run. The orchestrator sets them on the agent’s environment from the credential type before exec; the sidecar reads them once at startup and includes them on every POST /api/v1/internal/cost/record call.

Variable	Default	Description
`CREWSHIP_BILLING_MODE`	`metered`	`metered` (per-token $ math) or `flat_rate` (subscription credential, marginal cost = $0). Source: `internal/orchestrator/exec_env.go` (`exec_env.go:241,252`), `internal/sidecar/server.go:211`.
`CREWSHIP_SUBSCRIPTION_PLAN`	(empty)	Display label for flat-rate credentials. Currently the orchestrator hard-codes `"Anthropic Max"` for the OAuth Claude Code path; future credential types (`"Cursor Ultra"`, `"ChatGPT Plus"`) will surface their own labels. Set when `CREWSHIP_BILLING_MODE=flat_rate`; the Paymaster surfaces it on the Subscriptions panel. Source: `internal/orchestrator/exec_env.go`, `internal/sidecar/server.go:215`.

Operators do not set these manually for normal use. They are propagated automatically based on the credential’s auth type (API key → metered, OAuth/subscription → flat_rate). They are listed here only for sidecar-image authors and tooling that intercepts the orchestrator handoff.

See Paymaster for the full billing-mode model and Migrations for the v62 cost-ledger schema.

Ollama (Episodic Memory + Keeper)

Variable	Default	Description
`OLLAMA_MODELS`	`~/.ollama/models`	Directory where Ollama stores model blobs. Used by the Keeper gatekeeper LLM, the Episodic memory embedder, and the Consolidator. On macOS dev machines this is typically pointed at an external SSD: `OLLAMA_MODELS="/Volumes/SSD 990 PRO/ollama-models"`. Set this before starting Ollama (`./dev.sh start` or `ollama serve`); changing it requires a restart.

Feature toggles & runtime tuning

Variable	Default	Description
`CREWSHIP_CONSOLIDATE_HITL`	(unset — off)	Set to `1`/`true`/`yes`/`on` to route the memory consolidator through a human-in-the-loop approval step instead of writing directly. Read on every tick so it can be flipped without a restart. Read by `internal/consolidate/runner.go`.
`CREWSHIP_PIPELINE_RUNNER`	(unset — orchestrator runner)	Selects the pipeline execution backend. Set to `llm_direct` to run pipeline steps through the in-process LLM runner instead of spawning orchestrator containers (also the automatic fallback when no container provider is available). Read by `cmd/crewship/cmd_start.go`.
`CREWSHIP_PIPELINE_RESUME`	(unset — on)	Set to `off` to disable resuming interrupted pipeline runs after a server restart. Read by `cmd/crewship/cmd_start.go` / `internal/pipeline/runs.go`.
`CREWSHIP_MAX_CONCURRENT_RUNS`	`8`	Caps how many agent runs execute concurrently server-wide; excess runs queue. The primary throughput / memory-protection knob for busy instances. Non-positive or unparseable values are ignored. Read by `internal/orchestrator/orchestrator.go`.
`GITHUB_TOKEN`	(unset)	Any GitHub PAT raises the API rate-limit budget for the release probes behind `crewship self-update` / update checks. Useful on shared or CI hosts that exhaust the anonymous limit. Read by `internal/update/`.
`CREWSHIP_FORECAST_RATES`	(built-in rate table)	Overrides the provider price table used by `crewship cost forecast`. Format: `Name,inPerM,outPerM;Name,inPerM,outPerM;…` (USD per million tokens). Malformed entries fall back to the defaults with a one-time stderr warning. Read by `cmd/crewship/cmd_cost_forecast.go`.
`CREWSHIP_QUERY_DEPTH`	`0`	Default crew-to-crew query recursion depth when a request does not specify one. Hard-capped at `2` (deeper queries are rejected to prevent loops). Read by `internal/sidecar/query.go`.
`CREWSHIP_NOTIFY_LONG_RUN`	(built-in threshold)	Threshold in seconds above which the CLI emits a “long run” notification for an agent run. Read by `cmd/crewship/cmd_notify.go`.

Backup webhooks

Variable	Default	Description
`CREWSHIP_BACKUP_WEBHOOK_URL`	(unset — no webhook)	URL `POST`ed on every backup completion. Read by `internal/backup/webhook.go`.
`CREWSHIP_BACKUP_WEBHOOK_SECRET`	(unset)	HMAC signing key for the backup-webhook payload, so the receiver can verify authenticity. Read by `internal/backup/webhook.go`.

Operational skip flags (dev / CI)

These bypass safety or convenience behaviours. Never set them in production.

Variable	Default	Description
`CREWSHIP_SKIP_MIGRATION_BACKUP`	(unset)	Set to `1` to skip the pre-migration `crewship.db` snapshot. Never in production. Read by `internal/database/backup_pre_migrate.go`.
`CREWSHIP_SKIP_UPDATE_CHECK`	(unset)	Set to `1` to skip the daily “new version available” probe and the once-per-process CLI↔server version-skew warning. Read by `internal/update/check.go` and `internal/cli/version_skew.go`.
`CREWSHIP_SKIP_SIGNATURE_VERIFY`	(unset — gate on)	Set to `1` to skip the Sigstore/cosign signature verification of `checksums.txt` during `crewship self-update` (prints a loud warning). Only for air-gapped mirrors or forks whose releases sign under a different workflow identity. Read by `internal/update/selfupdate.go`.
`CREWSHIP_SKIP_SIDECAR`	(unset)	Set to `1` to bypass fail-fast sidecar autodetect (tests / container-less runs only). Also documented under Container. Read by `internal/config/config.go`.

License

Variable	Default	Description
`CREWSHIP_LICENSE_FILE`	(empty)	Path to license file

Seed Data

These variables are used by the ./dev.sh seed command:

Variable	Description
`SEED_ANTHROPIC_API_KEY`	Anthropic API key or OAuth token for demo agents
`SEED_GOOGLE_EMAIL`	Google email for seed Google credential
`SEED_GOOGLE_PASSWORD`	Google password for seed Google credential

Container Runtime

Variable	Description
`DOCKER_HOST`	Docker socket override (e.g., `unix:///var/run/docker.sock`)

The Docker provider checks DOCKER_HOST first, then auto-detects from candidate socket paths.

Devcontainer Cache GC

Crewship runs a background sweeper every 30 minutes that detects three kinds of leaks: temporary provisioning containers orphaned by a crewshipd crash (matched by the crewship-provision-* name and the crewship.temp=provision label — see Devcontainers → Background GC for why the name is the one that authorises deletion), unreferenced crewship-cache:* images left behind when the process is killed between docker commit and the database write that links the image to a crew, and intermediate crewship-feat:* BuildKit feature images (per-feature layers that are regenerable and never directly referenced by a crew row). Temp containers older than one hour are always removed. Cache and feature images are logged only by default; deletion must be explicitly enabled.

Variable	Default	Description
`CREWSHIP_CACHE_GC_AUTODELETE`	(unset)	Set to `true` or `1` to remove unreferenced `crewship-cache:` and intermediate `crewship-feat:` images automatically. Default behaviour is to log the orphans only — destructive removal is opt-in because deleting a freshly-built local image is surprising in interactive environments.

A 5-minute age floor protects images that were committed in the last few minutes (closing the race between docker commit and the DB update inside Provision()), so enabling auto-delete is safe even on busy systems.

Leave CREWSHIP_CACHE_GC_AUTODELETE unset on developer machines. Enable it on long-running production hosts where reclaiming disk matters more than preserving incidental cached images. Inspect the orphan list in the logs first to verify nothing important would be removed.

CLI client

These configure the crewship CLI on a developer/operator machine (not the server). They override values in ~/.crewship/cli-config.yaml. Resolution order and parsing live in internal/cli/config.go.

Variable	Default	Description
`CREWSHIP_SERVER`	`http://localhost:8080`	Base URL of the Crewship server the CLI talks to. Takes precedence over `server:` in the config file, but loses to a per-command `--server` flag.
`CREWSHIP_CONFIG`	`~/.crewship/cli-config.yaml`	Path to the CLI config file. Pin it to a per-instance path when running multiple clones on the same machine so their sessions don’t clobber each other.
`CREWSHIP_WORKSPACE`	(unset)	Default workspace ID/slug for commands that take one.
`CREWSHIP_DEFAULT_AGENT`	(unset)	Default agent the CLI targets when a command omits an explicit agent.
`CREWSHIP_TOKEN`	(unset)	Explicit CLI auth token — short-circuits the stored login entirely. The way to authenticate in CI or from an agent without a `crewship login` session.
`CREWSHIP_PROFILE`	(unset)	Select a named server profile from `cli-config.yaml` (`servers:` map). Resolution: `--profile` flag → this var → `directory_profiles` match → `current`. Manage with `crewship server`.
`CREWSHIP_HTTP_TIMEOUT`	`30`	CLI per-request timeout in seconds. Raise on slow links or long-running server calls.
`CREWSHIP_ALLOW_SERVER_MISMATCH`	(unset)	Set to `1` to allow sending the stored auth token to a `--server` host different from the one it was issued for (normally refused as a token-leak guard). Same as the `--server-allow-mismatch` flag.
`CREWSHIP_NO_SLUG_CACHE`	(unset — cache on)	Set to `1` to disable the workspace slug→ID disk cache (`~/.crewship/cache/workspace_slugs.json`, 15-minute TTL). The cache saves one `/workspaces` preflight round-trip per invocation when `--workspace` is a slug; disable it if you delete and recreate workspaces under the same slug in rapid succession. Read by `internal/cli/slugcache.go`.

Installer

Read by scripts/install.sh (the curl … | bash install path), not by the running server.

Variable	Default	Description
`CREWSHIP_VERSION`	(latest stable release)	Pin a specific release tag, e.g. `v0.1.0-beta.1`, instead of the latest stable.
`CREWSHIP_INSTALL_DIR`	auto (`$XDG_BIN_HOME` / `$HOME/.local/bin`, else `/usr/local/bin`)	Override the directory the binary is installed into.
`CREWSHIP_SKIP_VERIFY`	`0`	Set to `1` to skip checksum verification of the downloaded binary (not recommended).

Complete Example

# Secrets — optional: auto-generated on first boot and persisted to
# <dataDir>/secrets.env. Set these explicitly only when an external
# secret manager owns them (Vault, k8s secret, systemd EnvironmentFile).
# ENCRYPTION_KEY=a1b2c3d4e5f6...  # 64 hex chars
# NEXTAUTH_SECRET=your-jwt-secret

# Server
CREWSHIP_HOST=0.0.0.0
CREWSHIP_PORT=8080

# Container
CREWSHIP_CONTAINER_PROVIDER=docker
CREWSHIP_SIDECAR_ENABLED=true
CREWSHIP_RUNTIME_IMAGE=debian:bookworm-slim
# CREWSHIP_SIDECAR_PATH and CREWSHIP_ENTRYPOINT_PATH are normally autodetected:
# the release tar.gz/installer ships them next to crewship, Homebrew under
# libexec, and a source build emits them via `make build:sidecar`. Override only
# when running from an unusual layout.
# CREWSHIP_SIDECAR_PATH=/opt/crewship/crewship-sidecar
# CREWSHIP_ENTRYPOINT_PATH=/opt/crewship/entrypoint.sh

# Auth
CREWSHIP_ALLOW_SIGNUP=true

# Keeper (optional)
KEEPER_OLLAMA_URL=http://localhost:11434
KEEPER_MODEL=claude-haiku-4-5

# Logging
CREWSHIP_LOG_LEVEL=info
CREWSHIP_LOG_FORMAT=json

Validation

The config is validated at startup (Config.Validate). These constraints are enforced:

Field	Constraint
`server.port`	1-65535
`ipc.socket_path`	Non-empty
`container.provider`	`docker`, `apple`, or `auto`
`storage.provider`	`localfs`
`state.provider`	`bbolt`
`container.default_runtime`	`runc`, `runsc`, `kata-runtime`, or `sysbox-runc` (if set)
`auth.nextjs_url`	Non-empty

​Environment Variables

​Server

​IPC

​Container

​Runtime image pinning

​Set by Crewship inside the container

​Storage

​State

​Public-facing URL

​Origin enforcement (CORS / EnforceOrigin)

​Rate limiting & proxy trust

​Metrics

​Webhooks / hooks (SSRF guard)

​Profiling & observability

​Crash reporting (Sentry)

​Email (password recovery)

​Google sign-in (optional)

​Logging

​CLI and runtime context

​Authentication

​Auto-Derived Values

​Encryption

​Composio integrations

​Keeper (AI Security Gatekeeper)

​Local models (coding agents)

​LLM Proxy

​Paymaster (Billing Modes)

​Ollama (Episodic Memory + Keeper)

​Feature toggles & runtime tuning

​Backup webhooks

​Operational skip flags (dev / CI)

​License

​Seed Data

​Container Runtime

​Devcontainer Cache GC

​CLI client

​Installer

​Complete Example

​Validation

Environment Variables

Server

IPC

Container

Runtime image pinning

Set by Crewship inside the container

Storage

State

Public-facing URL

Origin enforcement (CORS / EnforceOrigin)

Rate limiting & proxy trust

Metrics

Webhooks / hooks (SSRF guard)

Profiling & observability

Crash reporting (Sentry)

Email (password recovery)

Google sign-in (optional)

Logging

CLI and runtime context

Authentication

Auto-Derived Values

Encryption

Composio integrations

Keeper (AI Security Gatekeeper)

Local models (coding agents)

LLM Proxy

Paymaster (Billing Modes)

Ollama (Episodic Memory + Keeper)

Feature toggles & runtime tuning

Backup webhooks

Operational skip flags (dev / CI)

License

Seed Data

Container Runtime

Devcontainer Cache GC

CLI client

Installer

Complete Example

Validation