Skip to main content

​
Your First Crew

A crew is a team of AI agents that work together on tasks. Each crew runs inside a shared Docker container, and agents communicate through the sidecar proxy.

​
Core Concepts

Crew

A named team with a shared container, identity, and purpose. One container per crew (not per agent).

Agent

An AI-powered worker with a persona, role, and tool profile. Runs as Exec inside the crew container.

Mission

A multi-task objective orchestrated by a Lead agent. Tasks can have dependencies and retry logic.

​
Agent Roles

Every agent has one of two roles that determines their capabilities:
Roles are functional, not hierarchical. A Lead is an equal colleague with orchestration responsibility — not a boss. This is a core Crewship philosophy (the “Crewship Adventure” ethos).

​
Creating a Crew

1

Navigate to the Crews page

Open the Crewship dashboard and click Crews in the sidebar.
2

Create a new crew

Click New Crew and fill in the details:
  • Name: A human-readable name (e.g., “Engineering”)
  • Slug: URL-friendly identifier (e.g., engineering)
  • Icon: A lucide icon name (terminal, rocket, clipboard, etc.) — not emoji
  • Color: A palette ID (blue, emerald, violet, amber, rose, cyan, lime, fuchsia) — not hex
3

Add agents to the crew

Each agent needs:
  • Name and slug: Identity (e.g., “Viktor” / viktor)
  • Role title: Human-readable role (e.g., “Backend Engineer”)
  • Agent role: AGENT or LEAD
  • CLI adapter: Which coding CLI to use (CLAUDE_CODE, CODEX_CLI, GEMINI_CLI, OPENCODE, CURSOR_CLI, FACTORY_DROID)
  • Tool profile: Controls available tools:
    • MINIMAL — Read-only: Read, Glob, Grep (plus MCP discovery)
    • CODING — Full coding tools
    • FULL — All tools available
  • System prompt: The agent’s persona and instructions
  • Memory enabled: Toggle persistent memory across sessions
4

Assign credentials

Add API keys for the LLM provider your agents will use. Credentials are encrypted with AES-256-GCM and injected via the sidecar proxy — never as environment variables.
Agents created from templates or through the internal API have credentials auto-assigned (autoAssignCredentials matches on provider). Agents created via the CLI or UI assign credentials manually.

​
Running Your First Mission

1

Send a message to a Lead agent

Navigate to the crew chat and send a task to the Lead:
2

Lead orchestrates the work

The Lead agent can:
  • Execute the task directly
  • Assign subtasks to other agents via /assign
  • Create a multi-task mission via /mission/create
3

Monitor progress

Watch real-time progress in the chat panel. Assignments appear with status indicators:
  • PENDING — Waiting to start
  • RUNNING — Agent is working
  • COMPLETED — Task finished successfully
  • FAILED — Task encountered an error

​
Crew Container Architecture

When a crew starts, Crewship creates a shared container with this filesystem layout:
Files agents create in /output/{slug}/ are immediately visible in the Files panel of the UI. Use the shared crew space at /crew/shared/ for cross-agent collaboration.
Agents in a crew trust each other. All agent processes in the container run as one Unix user (UID 1001), so the per-agent directories above are an organizational convention, not a security boundary — any agent can read a sibling’s home, output, and /secrets/{slug}/ files. The enforced isolation boundary is the crew container itself. Agents that must not see each other’s credentials belong in separate crews; see Credentials > The trust boundary is the crew.

​
System Prompt Assembly Order

For the full 2-stage breakdown, see Architecture > System Prompt Assembly. When an agent starts, its system prompt is assembled in this order:
The token budget is managed with a 60/40 split: 60% for conversation history, 40% for memory context. The maximum system prompt token budget is defined in internal/tokenutil/.

​
Example: Seed Data Crew

Want to skip manual setup? The built-in seed data ships a ready-made Engineering crew you can run a first mission against immediately.
The built-in seed data creates this Engineering crew: The seed also ships a Quality crew (Jordan, Casey) and an Ops crew (Morgan, Riley) — three crews and seven agents in total.