> ## 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
> Build Crewship from source, run the Go + Next.js dev servers via dev.sh, and lay out multi-instance and remote-dev environments.
# 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](/guides/install). For production deploy patterns
the [quickstart](/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
Required for building from source (`go.mod` declares `go 1.26`). The binary is statically compiled with `go:embed`.
Required only for development (frontend build). Not needed at runtime.
Agent containers run on Docker, Podman, Colima, OrbStack, Rancher Desktop, or Apple Containers.
A 256-bit hex-encoded key for AES-256-GCM credential encryption.
## Quick Start
```bash theme={null}
git clone https://github.com/crewship-ai/crewship.git
cd crewship
```
```bash theme={null}
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)
```
```bash theme={null}
./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_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.
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:
```bash theme={null}
./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 [ # Switch to ][ 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 ][` (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 form | Example | Result |
| ----------- | ------------------------------- | --------------------------------------------------- |
| Branch name | `./dev.sh deploy main` | Tracks `origin/main`, fast-forwards on next deploy. |
| Branch name | `./dev.sh deploy feat/my-thing` | Tracks `origin/feat/my-thing`. |
| GitHub PR | `./dev.sh deploy pr/220` | Fetches `refs/pull/220/head` and checks it out. |
| Git tag | `./dev.sh deploy v1.4.0` | Detached HEAD on the tag. |
| Commit SHA | `./dev.sh deploy 404650b7` | Detached 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 @ ()"` so the deploy never destroys a WIP. Recover with `git stash list` to find the entry, then `git stash apply ][` (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`:
| Directory | Go Port | Next.js Port |
| -------------------- | ------- | ------------ |
| `crewship` (default) | 8080 | 3001 |
| `crewship_1` | 8081 | 3011 |
| `crewship_2` | 8082 | 3012 |
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:
```bash theme={null}
# Check the API is responding (no auth)
curl http://localhost:8080/api/health
# Check container runtime detection (requires an auth token)
curl -H "Authorization: Bearer " \
http://localhost:8080/api/v1/system/runtime
```
## Seeding Demo Data
The `seed` command creates demo crews, agents, skills, and sample issues:
```bash theme={null}
./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)
]