> ## 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

> Three supported ways to install Crewship: Homebrew tap, signed curl | bash installer, or Docker Compose.

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

<CardGroup cols={3}>
  <Card title="Homebrew" icon="apple" href="#homebrew">
    macOS and Linuxbrew — one command, auto-upgrades.
  </Card>

  <Card title="curl | bash" icon="terminal" href="#curl--bash">
    OS-agnostic install script with SHA-256 + cosign verification.
  </Card>

  <Card title="Docker Compose" icon="docker" href="#docker-compose">
    Containerised, host doesn't need Go or Node.
  </Card>
</CardGroup>

## 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`.

```bash theme={null}
# 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.

<Note>
  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.
</Note>

The tap is auto-resolved from the prefixed name, so you do not need a separate `brew tap` step. Upgrades follow the normal flow:

```bash theme={null}
brew upgrade crewship       # or: brew upgrade crewship-cli
```

Once installed (full variant), jump to the [quickstart](/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.

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/crewship-ai/crewship/main/scripts/install.sh | bash
```

<Note>
  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.
</Note>

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](https://docs.sigstore.dev/cosign/system_config/installation/)
for full supply-chain verification.

### Pinning a version

```bash theme={null}
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:

```bash theme={null}
CREWSHIP_INSTALL_DIR=$HOME/.crewship/bin curl -fsSL https://raw.githubusercontent.com/crewship-ai/crewship/main/scripts/install.sh | bash
```

<Warning>
  `CREWSHIP_SKIP_VERIFY=1` disables checksum and signature verification.
  Use it only for offline mirror testing — never for normal installs.
</Warning>

### 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`](https://github.com/crewship-ai/crewship/blob/main/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

```bash theme={null}
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

<Note>
  **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.
</Note>

### 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](https://github.com/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](/security/threat-model).

## Verifying the install

After any of the three paths:

```bash theme={null}
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](/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](/guides/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.

## Related

* [Quickstart](/quickstart) — first run, admin bootstrap, seeding demo data.
* [Developer installation](/guides/installation) — building from source, `dev.sh`, multi-instance layout.
* [Environment variables](/configuration/environment) — full reference of `CREWSHIP_*` knobs.
* [Telemetry](/guides/telemetry) — opt-out before the first start if you prefer.