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.

​

Architecture

​

High-Level Architecture

                          +------------------+
                          |   User Browser   |
                          +--------+---------+
                                   |
                          HTTP / WebSocket
                                   |
                    +----------------------------------+
                    |         crewship binary           |
                    |  +----------------------------+   |
                    |  | Go HTTP Server (port 8080) |   |
                    |  +---+-----+-----+-----+-----+   |
                    |      |     |     |     |          |
                    |   REST  WS  SSE  IPC  Static     |
                    |   API  Hub       (Unix) Files     |
                    |      |     |     |     |          |
                    |  +---v-----v-----v-----v-----+   |
                    |  |       SQLite (embedded)    |   |
                    |  +----------------------------+   |
                    +--------+---------+----------------+
                             |         |
                    Docker API    Unix Socket IPC
                             |    (/tmp/crewship.sock)
                    +--------v---------v--------+
                    |    Crew Container          |
                    |  +---------+ +---------+   |
                    |  | Sidecar | | Agent   |   |
                    |  | (1002)  | | (1001)  |   |
                    |  +---------+ +---------+   |
                    +----------------------------+

​

Single Binary Design

1. Frontend: pnpm build creates a Next.js static export
2. Embedding: The out/ directory is copied to web/out/ and embedded via //go:embed
3. Compilation: go build produces a statically linked binary with version metadata

crewship binary
├── Go HTTP server (Gorilla mux, chi router)
├── WebSocket hub (real-time updates)
├── SQLite database (modernc.org/sqlite, driver: "sqlite")
├── Container orchestrator (Docker/Apple provider)
├── Sidecar proxy binary (embedded)
├── Embedded static frontend (web/out/*)
└── Seed data (crew/agent templates)

​

Container Model

Crew Container (crewship-team-{slug})
├── /crew/
│   ├── agents/{slug}/          # Per-agent home directory
│   │   ├── .memory/            # Persistent memory files
│   │   └── .mcp.json           # MCP server config
│   └── shared/                 # Cross-agent shared space
├── /output/{slug}/             # Agent output (visible in UI)
├── /secrets/{slug}/            # Read-only credentials
├── /workspace/                 # Temporary scratch
└── Processes:
    ├── Sidecar proxy (UID 1002, port 9119)
    └── Agent CLI exec (UID 1001, via docker exec)

​

UID Security Boundary

​

IPC (Inter-Process Communication)

Sidecar (in container)
    |
    | HTTP POST to crewshipd base URL
    | Header: X-Internal-Token: {auto-generated-token}
    v
crewshipd (/api/v1/internal/*)
    |
    | Process request (assignment, keeper, query)
    v
Response back to sidecar

token, err := generateRandomToken(32) // 32 bytes -> 64 hex chars

​

Orchestrator

1. Container management: Ensures crew containers exist via GetOrCreateContainer
2. Agent execution: Runs agents as docker exec commands inside crew containers
3. System prompt assembly: Builds the full prompt from preamble, persona, context, memory, and history
4. Credential selection: Picks the best credential via priority and round-robin
5. Activity tracking: Refreshes crew TTL on each agent run

​

System Prompt Assembly Order

1. [CREWSHIP ETHOS] — role-specific adventure context
2. [LANGUAGE PREFERENCE] — workspace preferred language (optional)
3. [AGENT IDENTITY] — name, role, crew
4. [PERSONA] — user-defined system prompt
5. [SKILLS AVAILABLE] — injected skill playbooks

6. Conversation history (60% of remaining token budget)
7. [CREW CONTEXT] (Lead) OR [PEER CONTEXT]
8. [AGENT MEMORY] (40% of remaining token budget)
9. [MEMORY INSTRUCTIONS] — how to read/write memory files

​

Sidecar Proxy

​

Core Functions

​

Network Modes

• Anthropic — api.anthropic.com (Claude Code API key + OAuth), console.anthropic.com (OAuth refresh callback)
• OpenAI / Codex — api.openai.com (API key), auth.openai.com (ChatGPT-subscription login), chatgpt.com (subscription routing)
• Google / Gemini — generativelanguage.googleapis.com (AI Studio path), oauth2.googleapis.com (OAuth), accounts.google.com (OAuth UI redirect)
• Cursor — api.cursor.sh (auth/billing), api2.cursor.sh (model gateway, since 2026-Q1)
• Factory Droid — api.factory.ai (legacy), app.factory.ai (CLI installer + API base)

​

Sidecar Endpoints (36 paths, 39 routes)

​

Keeper Request Lifecycle

​

Decision flow

1. L1 fast-path — for request only (never execute), an L1 credential plus an intent ≥ 10 non-whitespace characters AND ≥ 3 distinct non-whitespace characters is auto-allowed without an LLM round-trip. Single-character, whitespace-only, or trivial-filler intents like "aaaaaaaaaa" are rejected.
2. LLM evaluation — every other request is scored by Gatekeeper.Evaluate, which prompts a local Ollama model with the request, the agent’s recent conversation, and the credential’s SecurityLevel. The model returns a structured { decision, reason, risk } JSON object.
3. Fail-closed default — if no LLM provider is configured, the Gatekeeper returns DENY. The same applies if the LLM response cannot be parsed as JSON.
4. Execute branch only — on ALLOW, crewshipd runs the command via docker exec inside the crew container with the credential injected as an environment variable. Stdout and stderr pass through the scrubber before being returned. The credential value never crosses back into UID 1001.

​

Sequence diagram

​

Permission Scope

​

Threat Model

​

What Crewship protects against

• Agent leaking a credential into chat or logs. /keeper/execute runs the command in crewshipd, scrubs stdout/stderr, and only the redacted result reaches UID 1001.
• Unauthorised egress in restricted network mode. The proxy refuses non-allowlisted hosts. Unknown network modes default to restricted (fail-closed) rather than free, so a misconfigured workspace cannot accidentally open up egress.
• Credential dump from the agent process. Credentials are held in crewshipd’s process memory; UID 1001 can talk to UID 1002 over loopback but cannot read the sidecar’s process memory or files. Filesystem credentials at /secrets/{slug}/ are mounted read-only.
• Prompt injection in tool output. internal/lookout scans inputs and outputs; on a finding it either sanitises (default for secret-shaped output) or blocks (default for input). Every action is logged to the journal.
• Trivial fast-path bypasses. L1 auto-allow is gated to request only — an attacker cannot smuggle a command through the L1 path because execute always pays the LLM round-trip. Empty or whitespace-only intents are rejected before they reach the LLM.

​

What Crewship does NOT protect against

• A compromised host. Docker is the bottom of the trust stack. If the host kernel, Docker daemon, or root account is compromised, every credential and every journal entry is exposed. Run crewshipd on a hardened host; do not expose port 8080 publicly without an authenticating reverse proxy.
• A malicious or misconfigured Keeper LLM. If the Ollama model used by the Gatekeeper has been swapped for an adversarial one, ALLOW decisions cannot be trusted. Pin model digests, audit the model out-of-band, and treat the Keeper as a defense-in-depth layer rather than a primary control.
• Side channels in scrubbed output. The scrubber redacts known credential shapes. A sufficiently creative agent can still leak partial information through timing, exit codes, or format-string tricks. Treat /keeper/request as a weaker contract than /keeper/execute for genuinely sensitive secrets.
• Cross-tenant isolation on shared infrastructure. A single crewshipd process serves a single workspace database at a time. Hosting multiple tenants requires separate crewshipd instances with separate ENCRYPTION_KEYs and separate Docker daemons (or namespaces).
• Supply-chain compromise of the agent CLIs. Crewship invokes claude, opencode, codex, and similar binaries as-is. Pin their versions in any Dockerfile you control, and review their changelogs before bumping.

​

CLI Adapters

​

WebSocket Hub

​

Database

• Driver: modernc.org/sqlite (pure Go, no CGo)
• Migrations: Go-only in internal/database/migrate.go (never Prisma migrate)
• Prisma: Used only for TypeScript type generation (pnpm db:generate)
• State: Agent run states stored in BoltDB (bbolt); a PostgreSQL state provider is on the v0.2 roadmap for high-throughput deployments

​

Manifest System

• Installed packages: apt, npm, and pip packages installed during agent sessions
• Credentials used: Which credentials were active during setup
• Setup commands: Commands run to configure the container environment

​

Output Processing

• duration_ms — total execution time in milliseconds
• total_cost_usd — API cost for the run
• num_turns — number of conversation turns

​

Execution Wrapping

1. Line-buffered stdout: stdbuf -oL forces line-buffered output so JSON lines are flushed immediately for real-time streaming in the UI.
2. tmux session wrapping: When tmux is available, agent commands run inside a named tmux session (agent-{slug}). This provides:
   • Resilience against SSH disconnects
   • Named sessions for debugging (tmux attach -t agent-{slug})
   • FIFO-based output streaming to the orchestrator
3. FIFO for output streaming: A named pipe is created for stdout, allowing the orchestrator to read output asynchronously while the agent runs in a tmux session.
4. Exit code tracking: The exit code is written to a file so the orchestrator can determine success/failure even when the process runs inside tmux.

​

Background Services

​

Crew Journal Platform

​

Single-event-stream design

                  +-------------------+
                  |  journal_entries  |
                  |   (append-only)   |
                  +---------+---------+
                            |
        +-------------------+---------+------------------+----------------+
        |                   |         |                  |                |
  Paymaster            Watch        Episodic        Cartographer     Quartermaster
  (cost_ledger +       Roster       Memory          (checkpoints)    (eval_runs +
   budget_limits       (agent_      (journal_                         regression
   are the write       status row   embeddings                        report)
   side; reads         is the       BLOB index)
   come from the       live
   journal +           projection)
   rollups)

• Paymaster writes cost_ledger rows and emits llm.call / cost.incurred / budget.* entries.
• Watch Roster upserts agent_status and emits agent.status_change.
• Episodic memory selectively embeds a subset of journal entries into journal_embeddings.
• Cartographer anchors named checkpoints at journal cursors.
• Harbor Master queues approvals; transitions emit approval.*.
• Hooks fire on lifecycle events and emit hook.fired / hook.blocked.
• Quartermaster derives typed trajectories and metrics from the journal.

​

Write-path order (LLM call stack)

telemetry  ->  paymaster  ->  lookout  ->  raw provider

• Telemetry outermost so the span covers budget enforcement + guardrails + the network hop.
• Paymaster outside lookout so a blocked call still records a partial ledger row when appropriate (attempted-but-blocked audit) and a cache-eligible call doesn’t waste time on guardrails before being short-circuited.
• Lookout outside the raw provider so bad inputs never reach the LLM.

​

Adapter pattern: orchestrator decoupling

​

Schema footprint

• Migration 52 added 8 tables: journal_entries, journal_embeddings, agent_status, approvals_queue, checkpoints, hooks_config, cost_ledger, budget_limits.
• Migration 53 added eval_runs (Quartermaster’s durable replay/regression index with status + metrics columns).
• Migration 55 added journal_entries_fts (FTS5 mirror of summary + payload), journal_entries_archived (compaction sink with truncated payloads), memory_relations (A-Mem-style edge graph), and memory_health_snapshots (daily 5-metric scoring) — see Episodic memory.
• Migration 60 added a partial index on journal_entries (workspace_id, trace_id) WHERE trace_id IS NOT NULL to make run aggregation GROUP BY trace_id cheap.
• Migration 61 backfilled the legacy agent_runs table into journal entries, snapshotted the original rows to agent_runs_archive, and dropped agent_runs — journal_entries is now the single source of truth for runs.
• Migration 62 added 9 columns to cost_ledger for billing-mode-aware accounting (billing_mode, quota_remaining_pct, quota_window, subscription_plan, four rate_*_per_m snapshot columns, cost_confidence) plus a partial index on (workspace_id, billing_mode) — see Paymaster.

​

Runs as journal projections

​

Container snapshots — declared intent vs actual state

​

Journal emitter wiring

_, _ = h.journal.Emit(ctx, journal.Entry{...})