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.

​
Roles & Permissions

Crewship implements role-based access control at two levels: workspace roles (human users) and agent roles (AI agents within crews).

​
Workspace Roles (Human Users)

Users are assigned one of five roles within a workspace:
RoleLevelPermissions
OWNERHighestFull control, billing, delete workspace
ADMINHighManage users, crews, credentials, integrations
MANAGERMediumCreate and manage crews, view credentials
MEMBERStandardRead access to all workspace data
VIEWERLowestRead access to all workspace data
Roles are defined as the OrgRole enum in the Prisma schema: 
enum OrgRole {
  OWNER
  ADMIN
  MANAGER
  MEMBER
  VIEWER
}

​
Permission Mapping (Code Implementation)

The canRole() function in Go maps roles to three internal actions:
ActionAllowed RolesUsed For
readAll authenticated membersView crews, agents, missions, logs
createOWNER, ADMIN, MANAGERCreate crews, agents, credentials, missions
manageOWNER, ADMINDelete resources, manage members, update settings
In the current implementation, MEMBER and VIEWER have identical permissions (both map to read only). The distinction exists in the schema for future granularity (e.g., MEMBER may gain send_message or run_agent permissions).

​
Signup Control

New user registration is controlled by the CREWSHIP_ALLOW_SIGNUP environment variable (or auth.allow_signup in YAML config). When disabled, only existing users can invite new members.

​
Agent Roles

Every AI agent has one of two functional roles:

AGENT

Individual contributor. Executes tasks, writes code, runs tools. The standard role for most agents.

LEAD

Crew orchestrator. Assigns tasks to agents, creates missions, monitors progress. Has access to the full sidecar API.

​
Agent Role Capabilities

CapabilityAGENTLEAD
Execute tasksYesYes
Use memoryYesYes
Peer queriesYesYes
Assign tasksNoYes
Create missionsNoYes
See crew membersVia peersFull list

​
The Equality Principle

Agent roles are functional, not hierarchical. A Lead is an equal colleague with orchestration responsibility — not a boss. This is a core Crewship philosophy.
The system prompt for each role reflects this equality: AGENT:
You are part of a crew on the Crewship — an expedition with a shared purpose that transcends any individual.
LEAD:
You are a crew member with orchestration responsibility. You are not a boss — you are an equal colleague who carries the soul and mission of the expedition to the whole team.

​
Internal API Authentication

The internal API (sidecar-to-crewshipd communication) uses token-based authentication: 
X-Internal-Token: {auto-generated-64-char-hex-token}
This token is:
  1. Auto-generated cryptographically at startup if not configured
  2. Passed to sidecar processes via the IPC config
  3. Verified on every internal API request
Never hardcode the internal token. The auto-generation ensures each deployment gets a unique token. If you need to set it explicitly (e.g., for multi-server setups), use CREWSHIP_INTERNAL_TOKEN.

​
Container Security Boundaries

Agent processes run as UID 1001, while the sidecar runs as UID 1002. This prevents agents from:
  • Reading the sidecar’s credential store
  • Modifying network policy configuration
  • Accessing the IPC token
  • Tampering with the proxy’s authentication headers
See Container Isolation for details.

​
Credential Access Control

Credentials are protected by multiple layers:
  1. Workspace scoping: Credentials belong to a workspace
  2. Agent assignment: Credentials must be explicitly assigned to agents
  3. Encryption at rest: AES-256-GCM with versioned keys
  4. Sidecar injection: Agents never see raw credential values
  5. Keeper gating: L2+ credentials require AI evaluation
  6. Audit trail: All credential access is logged

​
JWT Authentication

User authentication uses JWT tokens signed with NEXTAUTH_SECRET:
  • WebSocket connections use short-lived tokens (ws_token_expiry, default 5 minutes)
  • API requests use session-based JWT tokens
  • Token validation is handled by the middleware layer