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.

​
Developer Installation

This page is for contributors and operators building from source. For end-user install paths (Homebrew, curl | sh, Docker Compose) see the Install guide. For production deploy patterns the quickstart is the shortest path. Crewship ships as a single binary that embeds the Next.js frontend, SQLite database, and Go backend. There is no separate Node.js runtime required at deployment time.

​
Prerequisites

Go 1.22+

Required for building from source. The binary is statically compiled with go:embed.

Node.js 20+ & pnpm

Required only for development (frontend build). Not needed at runtime.

Docker or compatible runtime

Agent containers run on Docker, Podman, Colima, OrbStack, Rancher Desktop, or Apple Containers.

Encryption key

A 256-bit hex-encoded key for AES-256-GCM credential encryption.

​
Quick Start

1

Clone the repository

git clone https://github.com/crewship-ai/crewship.git
cd crewship
2

Build the binary

make build
This runs three stages:
  1. pnpm build — builds the Next.js frontend as a static export into out/
  2. Copies out/ to web/out/ for Go embedding
  3. go build with version/commit ldflags into the crewship binary
Version information is embedded via ldflags:
-X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)
3

Start Crewship

./crewship start
The server starts on http://localhost:8080 by default. The frontend is served from the embedded static files.
crewship start auto-generates the secrets it needs on first boot — ENCRYPTION_KEY, NEXTAUTH_SECRET, and CREWSHIP_INTERNAL_TOKEN are all written to ~/.crewship/secrets.env (mode 0600) and reused on subsequent starts. No manual env file is required. To bring your own secrets (e.g. from a secret manager), export the matching env vars before running crewship start and the auto-generation is skipped for any that are already set.
4

Open the web UI and complete onboarding

Open http://localhost:8080 in a browser. With an empty database you’ll be redirected to /onboarding, where the wizard creates the first admin user, the initial workspace, and your first crew. No CLI bootstrap (crewship init, manual DB seeding, etc.) is part of the supported install flow.

​
Development Setup

For local development, use the dev.sh script which manages both the Go backend and Next.js dev server: 
./dev.sh start          # Start Go backend + Next.js dev server
./dev.sh stop           # Stop all services
./dev.sh restart        # Restart services
./dev.sh status         # Show service status, branch, SHA, dirty flag, last build
./dev.sh seed           # Seed demo data (crews, agents, skills)
./dev.sh nuke           # Reset database and start fresh
./dev.sh logs           # View service logs (logs:go / logs:next for one)
./dev.sh deploy <ref>   # Switch to <ref> and restart, auto-stashing WIP
Never start services manually in development. Always use ./dev.sh to ensure proper coordination between the Go backend and Next.js frontend.

​
./dev.sh deploy <ref> (PR #222)

The deploy subcommand is the safe way to flip a dev VM between branches, tags, SHAs, and PRs without losing in-flight work. It accepts four ref forms:
Ref formExampleResult
Branch name./dev.sh deploy mainTracks origin/main, fast-forwards on next deploy.
Branch name./dev.sh deploy feat/my-thingTracks origin/feat/my-thing.
GitHub PR./dev.sh deploy pr/220Fetches refs/pull/220/head and checks it out.
Git tag./dev.sh deploy v1.4.0Detached HEAD on the tag.
Commit SHA./dev.sh deploy 404650b7Detached HEAD on the SHA.
Lifecycle:
  1. Auto-stash — if the working tree, index, or untracked files are dirty, the script runs git stash push --include-untracked -m "dev.sh deploy auto-stash @ <branch> (<UTC timestamp>)" so the deploy never destroys a WIP. Recover with git stash list to find the entry, then git stash apply <ref> (the script prints this hint as part of its output). Use apply rather than pop so a mistake doesn’t drop the entry from the stash list.
  2. Fetch and checkout — resolves the ref, force-resets the working tree to it.
  3. Self-healing build — ensure_web_build_fresh() compares mtimes of frontend sources against .web-build-marker. When stale, runs the full pnpm build → cp -r out web/out sequence; when warm, the check completes in ~0.1s. This was added because skipping cp -r out web/out after pnpm build leaves web/out/ ~100 files behind, which the Go embed FS then serves as 404 unpredictably.
  4. Restart services — same path as ./dev.sh restart.
The same .web-build-marker keeps ./dev.sh start and ./dev.sh restart self-healing too. If you ever see “fresh pnpm build produces stale UI”, the marker file is the place to look. If you run a production instance behind a systemd timer or similar polling deployer, push your release ref (e.g. main:release) and let the timer fast-forward — never run an ad-hoc deploy directly on the prod host.

​
Multi-Instance Support

Crewship supports running multiple instances from directories named crewship_N:
DirectoryGo PortNext.js Port
crewship (default)80803001
crewship_180813011
crewship_280823012
Each instance uses its own SQLite database and state directory. Set CREWSHIP_CONTAINER_PREFIX to isolate Docker container names between instances.

​
Build Architecture

Source Code
    |
    v
pnpm build --> out/ (static HTML/JS/CSS)
    |
    v
cp out/ --> web/out/  (Go embed source)
    |
    v
go build --> crewship (single binary)
              |
              +-- //go:embed web/out/*
              +-- Go HTTP server (port 8080)
              +-- SQLite via modernc.org/sqlite
              +-- Container orchestrator
              +-- Sidecar proxy binary
The SQLite driver name is "sqlite", not "sqlite3". Crewship uses modernc.org/sqlite which registers under the "sqlite" driver name. Using "sqlite3" will cause a runtime panic.

​
Database Migrations

Never run prisma migrate. Prisma is used only for TypeScript type generation (pnpm db:generate). All database migrations are managed in Go via internal/database/migrate.go.

​
Verifying the Installation

After starting, verify everything is working: 
# Check the API is responding
curl http://localhost:8080/api/v1/health

# Check container runtime detection
curl http://localhost:8080/api/v1/internal/status

​
Seeding Demo Data

The seed command creates demo crews, agents, skills, and sample issues: 
./dev.sh seed
# Or with an Anthropic API key for functional agents:
SEED_ANTHROPIC_API_KEY=sk-ant-... ./dev.sh seed
This creates:
  • 4 crews: Engineering, Quality, DevOps, Research
  • 12 agents: Each with unique personas, roles, and system prompts
  • 5 skills: Network Probe, File Crafter, Web Scraper, Script Runner, System Inspector
  • Credentials: Anthropic API key (or OAuth token if sk-ant-oat prefix detected)