Skip to main content

​
Install Crewship

Crewship ships as a single, statically-linked Go binary with the Next.js frontend embedded via go:embed. There is no Node runtime at production deploy time, and the only hard dependency is a container runtime if you intend to run agents (Docker, Podman, Colima, OrbStack, Apple Containers, or Rancher Desktop). Pick the install path that matches how you run software locally — the three below are first-class and tested on every release.

Homebrew

macOS and Linuxbrew — one command, auto-upgrades.

curl | bash

OS-agnostic install script with SHA-256 + cosign verification.

Docker Compose

Containerised, host doesn’t need Go or Node.

​
Homebrew

The release pipeline publishes two Homebrew formulae on every tag to crewship-ai/homebrew-tap (PR #444): a full binary that runs the daemon + embedded Next.js UI + CLI, and a CLI-only binary that’s about half the size and only talks to a remote crewshipd. 
# Full — self-hosting users who'll run `crewship start` on this box
brew install crewship-ai/tap/crewship

# CLI-only — talks to a remote daemon (e.g. colleague.tail.ts.net:8080)
brew install crewship-ai/tap/crewship-cli
crewship (full)crewship-cli
Binary size (darwin/arm64, stripped)55 MB27 MB
crewship ask / crew / agent / credential / mission (HTTP-only)✅✅
crewship start (run the daemon)✅❌
crewship doctor (local Docker / Apple Container detection)✅❌
crewship admin (direct SQLite recovery)✅❌
crewship telemetry✅❌
crewship memory log/show/restore (local audit chain)✅❌
The two formulae declare conflicts: against each other, so Homebrew refuses to install both on one host. Both archives ship the binary under the same name (crewship), so existing scripts keep working when you switch formulae.
Running a daemon-only subcommand from the CLI-only binary produces cobra’s unknown command "start" error. If you need to bring up a daemon, install the full formula instead.
The tap is auto-resolved from the prefixed name, so you do not need a separate brew tap step. Upgrades follow the normal flow: 
brew upgrade crewship       # or: brew upgrade crewship-cli
Once installed (full variant), jump to the quickstart to bring the server up.

​
curl | bash

The one-liner installer detects your OS and architecture, downloads the matching release archive from GitHub, verifies the SHA-256 against the signed checksums.txt, and — when cosign is on your PATH — also verifies the keyless Sigstore signature against the expected GitHub Actions OIDC identity. 
curl -fsSL https://raw.githubusercontent.com/crewship-ai/crewship/main/scripts/install.sh | bash
The short https://crewship.ai/install alias will point at this script once the project website goes live; until then, fetch it straight from the repo as shown above.
Missing cosign produces a soft warning rather than a hard failure so the one-liner keeps working for first-time users — install it from sigstore.dev/cosign for full supply-chain verification.

​
Pinning a version

CREWSHIP_VERSION=v0.1.0-beta.1 curl -fsSL https://raw.githubusercontent.com/crewship-ai/crewship/main/scripts/install.sh | bash
Omitting the variable picks the latest stable tag.

​
Custom install directory

By default the script prefers a no-sudo user dir on your PATH ($XDG_BIN_HOME, then ~/.local/bin) and falls back to /usr/local/bin. Override with: 
CREWSHIP_INSTALL_DIR=$HOME/.crewship/bin curl -fsSL https://raw.githubusercontent.com/crewship-ai/crewship/main/scripts/install.sh | bash
CREWSHIP_SKIP_VERIFY=1 disables checksum and signature verification. Use it only for offline mirror testing — never for normal installs.

​
What the script does

  1. uname -sm → resolves OS-arch → picks the matching release archive.
  2. Downloads the archive and checksums.txt over TLS.
  3. Computes SHA-256 of the archive, matches against the line in checksums.txt.
  4. If cosign is present, verifies the archive’s signature against EXPECTED_CERT_IDENTITY_RE = https://github.com/crewship-ai/crewship/.github/workflows/release.yml@.* and EXPECTED_OIDC_ISSUER = https://token.actions.githubusercontent.com.
  5. Extracts and moves the crewship binary into the install directory.
Source: scripts/install.sh.

​
Docker Compose

The repo ships a production-grade compose file at docker/docker-compose.prod.yml. It builds an image from the checked-out source, brokers all Docker API access through a docker-socket-proxy sidecar (so the crewship container never touches the raw socket), and exposes the single port (8080 by default) on the host.

​
Quickstart

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

# NEXTAUTH_SECRET and ENCRYPTION_KEY are REQUIRED — set them in .env first.
cp .env.example .env   # then fill in the two secrets
docker compose -f docker/docker-compose.prod.yml up -d
NEXTAUTH_SECRET and ENCRYPTION_KEY are required — the compose file declares them with the ${VAR:?... is required} form, so the stack refuses to start if either is unset. Provide them via a project- root .env file (or the compose environment: block, an external vault, Docker secrets, a Kubernetes secret mount, …). The server is reachable on http://localhost:8080 once the healthcheck (/healthz) reports healthy — typically within 10 seconds.

​
Defaults

SettingDefaultOverride
Host port8080CREWSHIP_PORT in .env
DatabaseSQLite at /data/crewship.db (named volume crewship-db)DATABASE_URL
Storagelocal FS at /var/lib/crewship (named volume crewship-data)CREWSHIP_STORAGE_BASE_PATH
Logs/var/log/crewship (named volume crewship-logs)CREWSHIP_LOG_PATH
Container providerDockerCREWSHIP_CONTAINER_PROVIDER
State backendbboltCREWSHIP_STATE_PROVIDER
ENCRYPTION_KEY and NEXTAUTH_SECRET are required in the compose environment: block (the prod compose declares them with ${VAR:?... is required}, so an unset value aborts up). Set them in .env and they persist across restarts because Compose reads .env each time the stack starts.

​
PostgreSQL

PostgreSQL is on the v0.2 roadmap. The beta runs exclusively on SQLite via modernc.org/sqlite (single binary, WAL mode, no extra services). The server accepts only file: DSNs on DATABASE_URL — there is no Postgres driver in the binary today, so a postgres:// URL will not connect. The commented-out postgres: service block in docker/docker-compose.prod.yml is a placeholder for that v0.2 work; leave it commented for now.

​
Docker socket: brokered through a socket proxy by default

The prod compose does not mount /var/run/docker.sock into the crewship container. Instead it ships a Tecnativa docker-socket-proxy sidecar that holds the only :ro mount of the raw socket, and points crewship at it via DOCKER_HOST: tcp://docker-socket-proxy:2375. The proxy enforces a defaults-deny allow-list (CONTAINERS, EXEC, IMAGES, NETWORKS, VOLUMES, INFO, POST); widen it explicitly if you add a feature that needs another endpoint. The full container threat model is documented in the Security threat model.

​
Verifying the install

After any of the three paths: 
crewship version           # SHA + build date
crewship doctor            # runtime + data-dir + DB sanity check
crewship doctor runs the following checks (each PASS / WARN / FAIL with a one-line detail):
  • Container runtime detected and socket responds
  • Data directory present (with --fix it gets created)
  • Data directory writable
  • Database migration version current
  • Sidecar binary present
  • NEXTAUTH_SECRET is set
  • Server reachable on its configured port
--fix enables safe auto-repairs (currently: create the data directory if missing). To check whether crash-reporting telemetry is opted in, use crewship telemetry status instead — that’s a separate command. Next stop: quickstart for the first run and admin user bootstrap. For development work (running the Go server + Next.js dev server side-by-side), see Developer installation.

​
Air-gapped / offline installs

Download the release tarball + checksums.txt + (optionally) the cosign bundle from GitHub Releases on a network-connected machine, verify it manually with sha256sum -c and cosign verify-blob, and copy the binary to your target host. The binary has no runtime fetch behavior — no embedded analytics, no auto-update — so once it’s on disk you’re done. For air-gapped Docker hosts, docker save crewship-ai/crewship:v0.1.0-beta.1 into a tarball on a connected machine, transfer, then docker load on the target.