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
  • Crew: Optional for an AGENT — leave it empty for a workspace-wide agent (no crew; you can assign one later). A LEAD must belong to a crew.
  • 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 — creation does not prompt for one. An agent that ends up with none, and no crew credential to inherit, is flagged on its overview canvas: the Credentials cell warns “No credential assigned” instead of staying quiet.

​
The Crews screen

/crews is the fleet: crews on the left, the selected crew or agent on the right.
  • The explorer works like the Routines and Skills sidebars. Under the search, Status counts agents: All, Needs you (an agent in error or waiting on your decision), Working, Idle and Expired hires; pick one to list only those agents. Filter narrows by role (lead or member), model, runtime, hire type, activity (active in the last 24 h, this week, quiet for 7+ days, never ran) and crew health (needs a rebuild, credential gaps); a facet where every agent is alike is not offered. Each pick shows as a chip you can remove, and Status, filters and view are kept in the URL, so a link opens the same list. / jumps to the search.
  • View groups the list by crew (the default), by status, or not at all (A–Z), and sorts by crew size, name or last active. By crew, the crews that need a person come first (an agent in error, a failed or pending container build, a credential whose CLI is missing from the image, an agent waiting on a decision), then the running ones, then the idle majority, which folds after six behind “N more crews · Show all”. A crew’s lead is listed first, with a crown. Under each name is a line about the crew (missions running, or when it last worked) and, under each agent, its role; Show roles and activity in View turns both off for a denser list. Hover an agent for Chat, a crew for Add agent. Collapsed, the sidebar keeps the crew icons, with a dot on the ones that need a person.
  • The line under the search is the workspace’s real size (103 crews · 308 agents, from the API’s X-Total-Count), or “N crews · M agents match” while a search or filter is on; when nothing matches it says so and offers Clear.
  • Needs you sits above a crew’s tabs and only when there is something to do. Each row carries its verb: Build now / Retry build (rebuild the container image), Install gh (adds the devcontainer feature the readiness check named and rebuilds), Connect (a crew tool without a credential — opens it on Integrations), Inspect (an agent in error), Review (an agent waiting on a decision, in the inbox). A healthy crew shows no strip.
  • Settings → Integrations shows each crew tool’s transport, bound agents and auth state, with Connect beside a gap.
  • The roster (no selection) is a table on a desktop and a one-column list on a phone; the onboarding guide agent is never listed.
  • A selected crew opens on four tabs: Overview (the crew at a glance — its team, health and what needs a person; settings and delete live behind Crew administration), Team (its agents, and the people assigned to it), Work (the crew’s issues, missions and shared routines) and Memory — the knowledge the crew and its agents have retained, by scope (Agent knowledge, Shared with crew, Shared with workspace), with Refresh, an export for the agent and crew scopes, a link to the pending Knowledge proposals in the inbox, and an About me view of what agents have saved about you (saved preferences and per-agent notes, each with a Forget). See Agent memory.
Lists are windowed at 500 rows; when a fleet is larger the explorer says how many rows are not loaded and loads them on ask.

​
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.