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 options 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.

Debian / RPM packages

apt/dnf-managed install with a bundled systemd service.

Docker

Official multi-arch image, or Compose from source.

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 MB	27 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 bundled crewship-sidecar is always a Linux binary, even in the macOS archive and Homebrew formula — it is bind-mounted into your Linux agent containers and executed there, never on the host. Don’t be surprised when file reports it as an ELF executable on a Mac; that’s by design (#953).

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

uname -sm → resolves OS-arch → picks the matching release archive.
Downloads the archive and checksums.txt over TLS.
Computes SHA-256 of the archive, matches against the line in checksums.txt.
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.
Extracts and moves the crewship binary into the install directory.

Source: scripts/install.sh.

Debian / RPM packages

Every release publishes native .deb and .rpm packages (amd64 + arm64) alongside the archives. They install the crewship and crewship-sidecar binaries, the entrypoint.sh runtime helper, and a systemd unit so a VM or bare-metal host runs Crewship as a managed service.

# Debian / Ubuntu
sudo apt-get install ./crewship_<version>_linux_amd64.deb

# Fedora / RHEL / openSUSE
sudo dnf install ./crewship_<version>_linux_amd64.rpm

The package creates a locked crewship service account (and adds it to the docker group when Docker is installed), installs the unit, but deliberately does not enable or start it. There are no secrets to configure first — crewship auto-generates ENCRYPTION_KEY and NEXTAUTH_SECRET on first start and persists them under /var/lib/crewship:

# Enable + start when ready
sudo systemctl enable --now crewship
sudo systemctl status crewship

# Dashboard-only (no Docker)? Set the knob first, then start:
echo 'CREWSHIP_ARGS=--no-docker' | sudo tee -a /etc/crewship/crewship.env
sudo systemctl enable --now crewship

# Or try it in the foreground without Docker:
sudo -u crewship CREWSHIP_DATA_DIR=/var/lib/crewship crewship start --no-docker

Path	Purpose
`/usr/bin/crewship`, `/usr/bin/crewship-sidecar`	the binaries (on `PATH`)
`/usr/libexec/crewship/entrypoint.sh`	agent-container entrypoint (autodetected)
`/usr/lib/systemd/system/crewship.service`	the service unit
`/etc/crewship/crewship.env`	optional overrides (config file — survives upgrades)
`/var/lib/crewship`	database, auto-generated `secrets.env`, snapshots, memory blobs

Upgrades go through the package manager (apt-get install --only-upgrade crewship / dnf upgrade crewship). The postinstall runs systemctl try-restart, so a running service picks up the new binary automatically (with its pre-migration snapshot) while a stopped one is left alone. On these installs crewship self-update deliberately refuses and points you back at apt/dnf — see Upgrading & Downgrading.

Verifying package signatures

Release .deb / .rpm packages are GPG-signed with the Crewship Packages key (packages@crewship.ai, fingerprint EDE8 25B5 5FF8 7F7D 442B 82BA A5BA 4669 E217 C05C). The public key is committed at packaging/crewship-packages.pub:

curl -fsSLO https://raw.githubusercontent.com/crewship-ai/crewship/main/packaging/crewship-packages.pub

# deb — the signature is a debsigs-style `_gpgorigin` ar member (dpkg-sig
# cannot read this format); verify it with gpg over the other members:
gpg --import crewship-packages.pub
mkdir deb-verify && (cd deb-verify && ar x ../crewship_<version>_linux_amd64.deb)
cat deb-verify/debian-binary deb-verify/control.tar.* deb-verify/data.tar.* \
  | gpg --verify deb-verify/_gpgorigin -   # → "Good signature"

# rpm
sudo rpm --import crewship-packages.pub
rpm -K crewship_<version>_linux_amd64.rpm   # → "digests signatures OK"

A hosted APT/DNF repository (signed Release / repomd.xml) is a tracked follow-up. Package integrity can also be verified against the release checksums.txt.macOS notarization is pipeline-ready but currently INACTIVE. The release pipeline signs and notarizes the macOS artifacts only when the MACOS_SIGN_P12 signing certificate is configured, and it is not provisioned today — so published macOS builds are unsigned and Gatekeeper will still warn (“cannot be opened because the developer cannot be verified”) on first launch. Until the certificate is in place, verify the macOS download against checksums.txt and clear the quarantine attribute yourself:

xattr -d com.apple.quarantine ./crewship

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

Setting	Default	Override
Host port	`8080`	`CREWSHIP_PORT` in `.env`
Database	SQLite at `/data/crewship.db` (named volume `crewship-db`)	`DATABASE_URL`
Storage	local 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 provider	Docker	`CREWSHIP_CONTAINER_PROVIDER`
State backend	bbolt	`CREWSHIP_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.

Windows

Each release ships two native Windows builds (beta) on the releases page:

crewship-cli_<version>_windows_<arch>.zip — the lightweight CLI for driving a Crewship server running elsewhere (a Linux box, a NAS, WSL).
crewship_<version>_windows_<arch>.zip — the full daemon: server, dashboard, and agent orchestration on your Windows machine.

CLI against a remote server

# Unpack anywhere on PATH, then point it at your server:
$env:CREWSHIP_SERVER = "http://your-server:8080"
crewship.exe login
crewship.exe whoami

Full daemon (requires Docker Desktop)

Agents always run in Linux containers — install Docker Desktop (WSL 2 backend) first. The daemon finds it via the docker_engine named pipe automatically; a custom engine needs DOCKER_HOST set.

# Unpack the full zip anywhere on PATH — keep crewship-sidecar and
# entrypoint.sh next to crewship.exe (they are Linux artifacts the
# daemon mounts into agent containers; they never run on Windows).
crewship.exe start

Windows specifics:

Data lives under %USERPROFILE%\.crewship by default, as on other platforms. Server-style installs that set DATABASE_URL explicitly get machine-wide defaults under %ProgramData%\crewship (instead of the Unix /var/lib/crewship).
Hook commands run under cmd.exe /c instead of sh -c — write hook command lines in cmd syntax.
crewship self-update works: the running crewship.exe is parked as crewship.exe.old during the swap and cleaned up on the next run.
self-update --server (systemd orchestration) is Linux-only; on Windows update the binary and restart the daemon yourself.
SHA-256 checksums cover both zips (checksums.txt on the release); verify with Get-FileHash -Algorithm SHA256 crewship_*.zip.

Windows support is beta: the daemon is CI-cross-compiled and the container path relies on Docker Desktop’s WSL 2 file sharing. Report issues with the windows label.

Verifying the install

After any of these 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 — when it fails, the detail distinguishes installed but not running (with the exact start command, e.g. open -a Docker or sudo systemctl start docker) from not installed (with an OS-specific install pointer)
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 ghcr.io/crewship-ai/crewship:v0.1.0-beta.1 into a tarball on a connected machine, transfer, then docker load on the target. (The image publishes only to GHCR — there is no Docker Hub mirror, so the ghcr.io/ prefix is required.)

Quickstart — first run, admin bootstrap, seeding demo data.
Developer installation — building from source, dev.sh, multi-instance layout.
Environment variables — full reference of CREWSHIP_* knobs.
Telemetry — opt-out before the first start if you prefer.

Get Started

Guides

Security

Configuration

Manifest Reference

Install

Install Crewship

Homebrew

curl | bash

Debian / RPM packages

Docker

Homebrew

curl | bash

Pinning a version

Custom install directory

What the script does

Debian / RPM packages

Verifying package signatures

Docker Compose

Quickstart

Defaults

PostgreSQL

Docker socket: brokered through a socket proxy by default

Windows

CLI against a remote server

Full daemon (requires Docker Desktop)

Verifying the install

Air-gapped / offline installs

​Install Crewship

Homebrew

curl | bash

Debian / RPM packages

Docker

​Homebrew

​curl | bash

​Pinning a version

​Custom install directory

​What the script does

​Debian / RPM packages

​Verifying package signatures

​Docker Compose

​Quickstart

​Defaults

​PostgreSQL

​Docker socket: brokered through a socket proxy by default

​Windows

​CLI against a remote server

​Full daemon (requires Docker Desktop)

​Verifying the install

​Air-gapped / offline installs

​Related

Install Crewship

Homebrew

curl | bash

Pinning a version

Custom install directory

What the script does

Debian / RPM packages

Verifying package signatures

Docker Compose

Quickstart

Defaults

PostgreSQL

Docker socket: brokered through a socket proxy by default

Windows

CLI against a remote server

Full daemon (requires Docker Desktop)

Verifying the install

Air-gapped / offline installs

Related