crewship start
Starts the Crewship server. Single Go binary listens on HTTP (default
:8080), serves the embedded Next.js UI, and connects to a container
provider for agent runs.
What happens on start
- Configuration resolution. Reads
--config if given, else
defaults from env (CREWSHIP_*) and built-in defaults.
- Database open. Opens SQLite at
~/.crewship/crewship.db (or
--db override). Enforces WAL mode, 0600 file perms, foreign keys.
- Pre-migration snapshot. If any migrations are pending,
SnapshotBeforeMigrate writes a VACUUM INTO copy of the live DB
to <dbpath>.pre-migrate-vN-to-vM-<UTC>.bak before any DDL runs.
See Backup & Restore — automatic pre-migration snapshots.
- Migrations apply. Runs every pending migration in
internal/database/migrate.go order. Collision detection fails
loudly if the local DB has a different name applied at a given
version.
- Telemetry init. Reads consent from
app_settings. v0.1 beta
default is enabled if no row exists; opt out with crewship telemetry off. See Telemetry.
- Update check. Fires a goroutine that queries the GitHub Releases
API (cached 24h in
~/.crewship/cache/). Prints a banner to stderr
if a newer release is available. Skip with
CREWSHIP_SKIP_UPDATE_CHECK=1.
- Providers initialize. Docker (or whichever container runtime is
detected), localfs storage, bbolt state.
--no-docker skips the
container provider — useful for read-only browse mode without
running agents.
- HTTP server starts. Binds
0.0.0.0:8080 by default. WebSocket
on the same port at /ws. IPC socket at /tmp/crewship.sock.
- First-run welcome. If post-migration the
users table is empty
AND stdout is a TTY, prints a one-screen banner pointing at the
browser onboarding wizard (PR #441). Suppressed on non-TTY so
systemd journal / log scrapes stay clean. Query errors warn-and-
continue rather than fail the start — a stale or half-migrated
DB is already surfaced via the migration log.
Boot typically takes 1–3 seconds on a warm machine; first-ever start
(empty DB, full migration sweep) takes 5–10 seconds.
Flags
| Flag | Default | Effect |
|---|
--config <path> | $HOME/.crewship/config.yaml if present | Path to YAML config. CLI flags override config; config overrides env defaults. |
--db <url> | file:~/.crewship/crewship.db | SQLite DSN (file:...). PostgreSQL on the v0.2 roadmap. |
--no-docker | (off) | Skip the Docker provider init. Useful for read-only browse mode or sandboxed CI. |
--verbose, -v | (off) | Switch logger to debug. Default is INFO. (Global root flag, available on every command.) |
--no-color | (off) | Disable ANSI colors in logs. Auto-detected when stdout is not a TTY. (Global root flag.) |
There are no --port, --host, or --license flags on crewship start.
HTTP port and bind address come from config / env only — set CREWSHIP_PORT
(default 8080) and bind 0.0.0.0 by default (see the env table below).
Licensing is read from config / env, not a command-line flag; without a
license, community-edition limits apply (max crews, agents, members).
Environment variables
Beyond the flags above, crewship start respects:
| Var | Default | Effect |
|---|
CREWSHIP_PORT | 8080 | HTTP listen port. (There is no --port flag — set it here.) |
CREWSHIP_SOCKET_PATH | /tmp/crewship.sock | IPC socket for sidecar coordination. |
CREWSHIP_CONTAINER_NETWORK | crewship-agents | Docker bridge name for agent containers. |
CREWSHIP_CONTAINER_PROVIDER | docker | docker, apple, or auto. |
CREWSHIP_STORAGE_PROVIDER | localfs | Where workspace files live. |
CREWSHIP_STATE_PROVIDER | bbolt | KV store for ephemeral run state. |
CREWSHIP_SKIP_MIGRATION_BACKUP | (unset) | Skip pre-migration snapshot. Don’t use on machines with valuable data. |
CREWSHIP_SKIP_UPDATE_CHECK | (unset) | Skip the daily GitHub Releases API check. |
CREWSHIP_SENTRY_DSN | (unset) | Override the vendor-baked Sentry DSN. Route crash reports to your own Sentry instance. See Telemetry — routing. |
NEXTAUTH_SECRET | Auto-generated on first boot | Auth session signing key. If not in env, generated via crypto/rand (32 bytes → 64 hex chars) and persisted to <dataDir>/secrets.env (mode 0600). Set explicitly for clustered deployments. |
ENCRYPTION_KEY | Auto-generated on first boot | Credential vault AES-256-GCM key. Same auto-gen + persist path as NEXTAUTH_SECRET. |
crewship start auto-bootstraps NEXTAUTH_SECRET, ENCRYPTION_KEY, and CREWSHIP_INTERNAL_TOKEN on first boot — curl install.sh | bash → crewship start works with no env files to hand-edit. Subsequent boots read the persisted file. Explicit env vars always win, so Vault / Kubernetes secret mounts / systemd EnvironmentFile= keep working unchanged. Run crewship doctor to see where each secret lives (“env-provided” vs “auto-managed in <path>”). See Configuration → Environment for the full bootstrap pipeline.
Multi-instance setup
Crewship can run multiple instances on one host by suffixing the
data directory and port. The dev.sh script handles this for
development; for production, point --db and CREWSHIP_PORT at
distinct paths:
CREWSHIP_PORT=8081 crewship start --db file:/opt/crewship-1/crewship.db
CREWSHIP_PORT=8082 crewship start --db file:/opt/crewship-2/crewship.db
CREWSHIP_CONTAINER_NETWORK=crewship-agents-1), separate
IPC socket (CREWSHIP_SOCKET_PATH=/tmp/crewship-1.sock).
Graceful shutdown
crewship start traps SIGINT and SIGTERM:
- Stops accepting new HTTP requests
- Finishes in-flight requests up to 30s
- Flushes Sentry events (2s timeout)
- Closes the database with WAL checkpoint
- Closes the docker client
Force-kill with kill -9 if shutdown takes longer than 30s; expect a
WAL replay on next boot (SQLite handles it automatically, just slower
than a clean shutdown).
