Skip to main content

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

Required for building from source (go.mod declares go 1.26). The binary is statically compiled with go:embed.

Node.js 22+ & pnpm

Required only for development (frontend build; package.json pins node >=22.13). 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

2

Build the binary

This runs three stages:
  1. pnpm build — builds the Next.js frontend as a static export into out/
  2. Stages out/ into web/out/ for Go embedding (scripts/embed-web-out.sh sync)
  3. go build with version/commit ldflags into the crewship binary
Version information is embedded via ldflags:
3

Start Crewship

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_ADMIN_TOKEN_HMAC_KEY are all written to ~/.crewship/secrets.env (mode 0600) and reused on subsequent starts. (CREWSHIP_INTERNAL_TOKEN is also auto-generated when unset, but in-memory per boot rather than persisted.) 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 /bootstrap, which creates the first admin user (POST /api/v1/bootstrap), then on to the /onboarding wizard for the initial workspace, LLM credential, and your first crew.Prefer the terminal? crewship init --email you@example.com --name "You" hits the same bootstrap endpoint, and crewship setup mirrors the onboarding wizard — see the quickstart for the CLI-first path. (Manual DB seeding is not supported.)

​
Development Setup

For local development, use the dev.sh script which manages both the Go backend and Next.js dev server:
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: 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 → scripts/embed-web-out.sh sync sequence; when warm, the check completes in ~0.1s. This was added because skipping the staging step 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: Each instance uses its own SQLite database and state directory. Set CREWSHIP_CONTAINER_PREFIX to isolate Docker container names between instances.

​
Build Architecture

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:
See Which container runtime is Crewship actually using? for the payload and the admin console panel that renders it.

​
Seeding Demo Data

The seed command creates demo crews, agents, skills, and sample issues:
This creates:
  • 3 crews: Engineering, Quality, Ops
  • 7 agents: Each with unique personas, roles, and system prompts (Engineering: Alex, Sam, Robin; Quality: Jordan, Casey; Ops: Morgan, Riley)
  • 5 skills: Network Probe, File Crafter, Web Scraper, Script Runner, System Inspector
  • Credentials: Anthropic API key (or Claude Code OAuth token if the sk-ant-oat prefix is detected)