Installation

COMA is one binary, coma, that runs on your laptop. Nothing is installed on the machine until you ask for it (see Bootstrap a bare VM).

Supported platformsCopy Anchor Link

The coma client runs on:

The machines your containers run on are Linux servers reached over SSH.

Get accessCopy Anchor Link

Install a release (repository access)Copy Anchor Link

If you have access to the COMA repository, install with the GitHub CLI, signed in with that account. The repository's README has the command; it runs the repository's scripts/install.sh, which:

1. picks the newest release, or the version you name;
2. downloads the archive for your OS and architecture with gh release download;
3. checks the archive against the release's SHA256SUMS and stops if it does not match;
4. installs coma into ~/.local/bin (no sudo needed), or into COMA_BINDIR if you set it;
5. installs COMA's sync helper, coma-sync, and its files into the sibling lib/coma directory (~/.local/lib/coma by default), where coma looks for it;
6. runs coma version, and tells you if the install directory is not on your PATH.

If comad, COMA's background process, was running an older version, stop it so the next command starts the new one:

coma daemon stop

Build from sourceCopy Anchor Link

The source is in the same private repository. Building needs Go; the Makefile sets GOTOOLCHAIN=auto, so an older local Go downloads the toolchain the repository pins.

Build bin/coma for this computer:

make build

Build and install coma into ~/.local/bin and coma-sync into ~/.local/lib/coma:

make install

make install takes BINDIR to install somewhere else; coma-sync then goes into BINDIR/../lib/coma. Building coma-sync downloads a pinned Mutagen release through the Go module proxy and checks its hash.

Without coma-sync, sync falls back to COMA's builtin engine, and coma doctor warns about it.

Check the installCopy Anchor Link

Print the build information:

coma version

coma v0.1.0-rc.4-3-g07087e6
  commit:  07087e66d988a2a7ac86c47d894564529dbae6ac
  built:   2026-10-04T10:23:36Z
  go:      go1.27.1
  os/arch: darwin/arm64

Then check the installation:

coma doctor

coma doctor checks the build, platform, file locations, config, state database and current context, then the laptop's own tools: local engines, Docker credential helpers, Compose v1 on PATH, a podman CLI that does not follow the connected engine, and the sync helper. Every check prints PASS, WARN or FAIL with a hint. Some lines from a fresh install:

PASS  version                coma v0.1.0-rc.4-3-g07087e6 (07087e66d988), go1.27.1
PASS  platform               darwin is supported
PASS  current-context        no current context selected
PASS  sync-helper            /Users/you/.local/lib/coma/coma-sync (Mutagen)

14 passed, 0 warnings, 0 failed

coma doctor exits with code 10 when any check fails. See Troubleshooting and Exit codes.

NextCopy Anchor Link

Add your first machine: Quickstart.