Skip to main content

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.

​
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://crewship.ai/install | bash
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://crewship.ai/install | bash
Omitting the variable picks the latest stable tag.

​
Custom install directory

By default the script picks the first writable directory on your PATH (/usr/local/bin, ~/.local/bin, ~/bin, …). Override with: 
CREWSHIP_INSTALL_DIR=$HOME/.crewship/bin curl -fsSL https://crewship.ai/install | 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, runs the binary as the crewship user, mounts the Docker socket read-only so agents can be launched, and exposes the single port (8080 by default) on the host.

​
Quickstart

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

docker compose -f docker/docker-compose.prod.yml up -d
ENCRYPTION_KEY and NEXTAUTH_SECRET are generated and persisted on the data volume the first time the container starts — no .env is required for the happy path. To bring your own secrets (external vault, Docker secrets, Kubernetes secret mount, …), set them via the compose environment: block and the auto-generation step is skipped for any value that’s already non-empty. 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 auto-generated by the binary on first boot and persisted to the data volume at /data/secrets.env (mode 0600); they are not required in the compose environment: block. The values survive container restarts because they live on the named volume, not in the container layer.

​
PostgreSQL mode

For multi-user deployments where SQLite contention becomes a concern, the compose file ships with a commented-out PostgreSQL service. To enable:
  1. Uncomment the postgres: service block and the crewship-pgdata: named volume.
  2. Set DATABASE_URL=postgres://crewship:${POSTGRES_PASSWORD}@postgres:5432/crewship and POSTGRES_PASSWORD in .env.
  3. Restart the stack.
The Crewship binary picks Postgres up from the postgres:// scheme on DATABASE_URL; the rest of the configuration is identical. The default compose mount is /var/run/docker.sock:/var/run/docker.sock:ro. Read-only on the host, but the container still has Docker API access, which is functionally root on the host. For production, swap it for a Tecnativa docker-socket-proxy with a minimal allow-list (CONTAINERS=1, EXEC=1, IMAGES=1, POST=1). The compose file calls this out in a comment. 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.