Documentation Index
Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
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 | /tmp/crewship.sock | Unix socket path for internal IPC |
Container
| Variable | Default | Description |
|---|
CREWSHIP_CONTAINER_PROVIDER | docker | Container provider: docker, apple, auto (Kubernetes provider on the v0.2 roadmap) |
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_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 or s3 |
CREWSHIP_STORAGE_BASE_PATH | /var/lib/crewship | Base path for local file storage |
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 | /var/lib/crewship/state.db | BoltDB file path |
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. |
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). 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. |
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>). |
Google sign-in (optional)
| 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 |
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 on first boot | Token for sidecar-to-crewshipd IPC authentication. Same auto-gen + persist path as NEXTAUTH_SECRET; stays stable across restarts once the file exists. |
CREWSHIP_ALLOW_SIGNUP | false | Allow new user registration (true or 1) |
As of PR #446 (internal/secrets), NEXTAUTH_SECRET, ENCRYPTION_KEY and CREWSHIP_INTERNAL_TOKEN are all 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). For clustered deployments, set them 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: Auto-generated on first boot and persisted (see Note above). Stays stable across restarts.
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) |
Keeper (AI Security Gatekeeper)
| Variable | Default | Description |
|---|
KEEPER_ENABLED | false | Enable Keeper AI gatekeeper (true or 1) |
KEEPER_OLLAMA_URL | http://localhost:11434 | Ollama API URL for Keeper LLM |
KEEPER_MODEL | phi3:mini | Ollama model name for Keeper evaluations |
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.
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:142,153, internal/sidecar/server.go:168. |
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:143, internal/sidecar/server.go:172. |
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.
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. |
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) |
DOCKER_HOST first, then auto-detects from candidate socket paths.
Devcontainer Cache GC
Crewship runs a background sweeper every 30 minutes that detects two kinds
of leaks: temporary provisioning containers orphaned by a crewshipd crash
(matched by the crewship.temp=provision label) and 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.
Temp containers older than one hour are always removed. Cache 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:* 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. |
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.
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
# from `make build:sidecar` output. Override 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=phi3:mini
# 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 or s3 |
state.provider | bbolt |
container.default_runtime | runc, runsc, kata-runtime, or sysbox-runc (if set) |
auth.nextjs_url | Non-empty |
