Skip to main content

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.

​
YAML Configuration

Crewship can be configured via a YAML file passed at startup. Environment variables override YAML values. The config is loaded and validated in internal/config/config.go.

​
Loading Order

1. Default values (config.Default())
2. YAML config file (if path provided)
3. Environment variable overrides (applyEnvOverrides)
4. Auto-derived values (NextjsURL, InternalToken)
5. Validation (Config.Validate)

​
Complete Reference

# Server configuration
server:
  host: "0.0.0.0"              # Listen address
  port: 8080                    # Listen port
  shutdown_timeout: 10s         # Graceful shutdown timeout

# Inter-process communication
ipc:
  socket_path: "/tmp/crewship.sock"  # Unix socket for internal API

# Container provider
container:
  provider: "docker"            # "docker" | "apple" | "auto"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runc"       # "runc" | "runsc" | "kata-runtime" | "sysbox-runc"
  network: "crewship-agents"    # Docker bridge network name
  container_prefix: ""          # Name prefix for multi-instance isolation
  default_memory_mb: 512        # Default container memory limit
  default_cpus: 1.0             # Default container CPU limit
  sidecar_enabled: false        # Enable sidecar proxy for credential injection

# Note: Crewship injects the sidecar binary and entrypoint script into the
# container at runtime via bind mount from the host. Any glibc-based Linux
# image (debian, ubuntu, or a derivative) works out of the box — no custom
# base image is required.

# File storage
storage:
  provider: "localfs"           # "localfs" | "s3"
  base_path: "/var/lib/crewship"
  log_path: "/var/log/crewship"

# State store (agent run states)
state:
  provider: "bbolt"             # "bbolt" (postgres on the v0.2 roadmap)
  bolt_path: "/var/lib/crewship/state.db"

# Logging
logging:
  level: "info"                 # "debug" | "info" | "warn" | "error"
  format: "json"                # "json" | "text"

# Authentication
auth:
  jwt_secret: ""                # NEXTAUTH_SECRET (required)
  ws_token_expiry: 5m           # WebSocket token expiry
  nextjs_url: ""                # Auto-derived from port if unset
  internal_token: ""            # Auto-generated if empty
  allow_signup: false           # Allow new user registration

# LLM proxy (token management)
llm_proxy:
  enabled: true
  token_sync_interval: 30s      # How often to sync token usage
  health_check_interval: 60s    # LLM provider health checks

# Keeper (AI security gatekeeper)
keeper:
  enabled: false
  ollama_url: "http://localhost:11434"
  model: "phi3:mini"

# License
license:
  file_path: ""                 # Path to license file

​
Section Details

​
Server

server:
  host: "0.0.0.0"
  port: 8080
  shutdown_timeout: 10s
The shutdown_timeout controls how long the server waits for in-flight requests to complete during graceful shutdown. The server port must be between 1 and 65535.

​
Container

container:
  provider: "docker"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runc"
  network: "crewship-agents"
  container_prefix: ""
  default_memory_mb: 512
  default_cpus: 1.0
  sidecar_enabled: false
ProviderDescription
dockerStandard Docker (auto-detects Docker, Podman, Colima, OrbStack, Rancher)
appleApple Containers on macOS Tahoe+ (lightweight VMs)
autoAuto-detect between docker and apple
Kubernetes provider is on the v0.2 roadmap.
RuntimeSecurityPerformance
runcStandard Linux namespacesFast
runsc (gVisor)Kernel-level syscall interceptionModerate
kata-runtimeLightweight VM isolationSlower
sysbox-runcEnhanced container isolationModerate
The container_prefix is prepended to container names. For example, with container_prefix: "prod", a container would be named prod-team-engineering instead of crewship-team-engineering. Essential for multi-instance deployments.

​
Storage

storage:
  provider: "localfs"
  base_path: "/var/lib/crewship"
  log_path: "/var/log/crewship"
The base_path stores crew workspace files, agent output, and persistent data. The log_path stores agent execution logs.

​
State

state:
  provider: "bbolt"
  bolt_path: "/var/lib/crewship/state.db"
BoltDB is the default state store for agent run tracking. A PostgreSQL state provider for high-throughput deployments is on the v0.2 roadmap.

​
Auth

auth:
  jwt_secret: ""           # Set via NEXTAUTH_SECRET env var
  ws_token_expiry: 5m
  nextjs_url: ""           # Auto-derived: http://localhost:{port}
  internal_token: ""       # Auto-generated if empty
  allow_signup: false
Never commit the jwt_secret or internal_token to version control. Use environment variables for sensitive values.

​
LLM Proxy

llm_proxy:
  enabled: true
  token_sync_interval: 30s
  health_check_interval: 60s
The LLM proxy manages token usage tracking and provider health monitoring.

​
Keeper

keeper:
  enabled: false
  ollama_url: "http://localhost:11434"
  model: "phi3:mini"
For development, start Ollama with models on an external SSD:
OLLAMA_MODELS="/Volumes/SSD/ollama-models" ollama serve
Then enable Keeper: KEEPER_OLLAMA_URL=http://localhost:11434 ./dev.sh start

​
Minimal Configuration

As of PR #446, no env vars are required for first boot. Run crewship start against an empty data directory and the server will:
  • Listen on 0.0.0.0:8080
  • Use Docker as container provider
  • Store data in ~/.crewship (or $CREWSHIP_DATA_DIR)
  • Use BoltDB for state
  • Auto-generate ENCRYPTION_KEY, NEXTAUTH_SECRET, and CREWSHIP_INTERNAL_TOKEN with crypto/rand, persisting them to <dataDir>/secrets.env at mode 0600
  • Auto-derive the NextJS URL from the listen port
Set env vars only when you need to override a default (different port, external secret manager, custom data dir, etc.). See Environment Reference for the full list.

​
Production Configuration

server:
  host: "0.0.0.0"
  port: 8080
  shutdown_timeout: 30s

container:
  provider: "docker"
  runtime_image: "debian:bookworm-slim"
  default_runtime: "runsc"      # gVisor for production security
  network: "crewship-agents"
  default_memory_mb: 1024
  default_cpus: 2.0
  sidecar_enabled: true

storage:
  provider: "localfs"
  base_path: "/data/crewship"
  log_path: "/var/log/crewship"

state:
  provider: "bbolt"
  bolt_path: "/var/lib/crewship/state.db"

logging:
  level: "info"
  format: "json"

auth:
  allow_signup: false

keeper:
  enabled: true
  ollama_url: "http://ollama-host:11434"
  model: "phi3:mini"