Add a machine

A machine is a Linux server COMA reaches over SSH: a cloud VM, a home server or bare metal. You register it once with coma machine add. See Machines for the model.

Add itCopy Anchor Link

coma machine add <name> ssh://user@host[:port]

coma machine add dev ssh://you@203.0.113.10

The ssh:// prefix is optional, and the port defaults to 22:

coma machine add dev you@203.0.113.10:2222 --identity ~/.ssh/dev

COMA connects over SSH with its own SSH client, verifies the host key, and records an inventory. It never changes anything on the machine.

AuthenticationCopy Anchor Link

COMA tries ssh-agent, then the key files you pass with --identity (repeatable), then ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa and ~/.ssh/id_rsa. Load passphrase-protected keys into ssh-agent: COMA never asks for or stores a passphrase.

From ~/.ssh/config, COMA honours HostName, User, Port and IdentityFile; values you pass explicitly win. A host that needs ProxyJump fails with ssh_proxy_failed instead of connecting some other way.

Host-key verificationCopy Anchor Link

COMA verifies host keys strictly. There is no silent trust-on-first-use.

• A key you already trust in ~/.ssh/known_hosts is accepted. COMA reads that file but never writes to it.

• An unknown key needs your confirmation. In a terminal, COMA shows the key type and fingerprint and asks whether to trust it. Compare it with the key on the server, for example:

  Copy Text

  ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

• Without a terminal (scripts, coding agents, --no-input), COMA does not prompt. It fails with ssh_host_key_unknown, and the error names the fingerprint the server presented. Verify it, then pass it with --host-key:

  Copy Text

  coma machine add dev you@203.0.113.10 --host-key SHA256:<fingerprint> --no-input

• A changed key is fatal: ssh_host_key_mismatch. A reinstalled server and a man-in-the-middle look the same, so COMA will not connect. Verify the new fingerprint with the server's owner, then remove the old entry from the file the error names.

COMA records the keys you trust in its own known_hosts file, next to its state database. More in the Security model.

What COMA recordsCopy Anchor Link

coma machine add stores, in COMA's local state on your laptop:

• the name, the SSH target, and the host key's type and fingerprint;
• the inventory: OS, architecture, CPU count, memory and free disk on /;
• the Docker and Podman engines it found, with their versions and health;
• the machine's health: reachable, authenticated, disk pressure, clock skew, and whether an engine is ready;
• an optional --description and --label key=value labels.

Added machine dev (ssh://you@203.0.113.10)
  Ubuntu 24.04.3 LTS · linux/amd64 · 8 CPUs · 31.3 GiB memory · 142.6 GiB free on /
  engines: none found
  health:  degraded (observed 2026-10-04 14:02)
    EngineReady: no Docker or Podman found; install one with `coma machine bootstrap <machine> --engine docker`
Next: coma machine bootstrap dev --engine docker

A machine without a working engine is degraded: it cannot run containers yet.

--discover=false records the machine without connecting. Its inventory stays empty until you run coma machine discover.

The next stepCopy Anchor Link

The Next: line is the command that moves the machine toward running containers:

It never suggests coma use: that sets COMA's default target, but your docker CLI keeps pointing where it was. See Contexts.

List machinesCopy Anchor Link

coma machine list

NAME  TARGET                  HEALTH   ARCH   CPUS  MEMORY    ENGINES
dev   ssh://you@203.0.113.10  healthy  amd64  8     31.3 GiB  docker 28.2.2

list (alias ls) reads local state only; it does not connect to any machine.

Inspect a machineCopy Anchor Link

coma machine inspect dev

inspect shows what COMA knows, from its cache: the machine's ID, target, host key, inventory, engines and health. It does not connect.

Refresh the inventoryCopy Anchor Link

coma machine discover dev

discover connects, verifies the host key, and refreshes the inventory and health. It is read-only on the machine. Run it after you install or change an engine yourself. If COMA does not know the host key yet, pass --host-key.

Forget a machineCopy Anchor Link

coma machine remove dev

Removed machine dev from COMA. The server itself was not changed.

remove (alias rm) only forgets the machine. The server, its engine and its containers are left as they are.

If a COMA context uses the machine, remove fails with machine_in_use and names the contexts. --detach clears the machine from those contexts and removes it:

coma machine remove dev --detach

Scripts and coding agentsCopy Anchor Link

Every coma machine command takes --json. With --no-input, COMA never prompts and fails with the flag to use instead. See JSON output.

NextCopy Anchor Link

• Bootstrap a bare VM if the machine has no engine.
• Quickstart to connect and run Compose.