Machines

A machine is a container execution target: a Linux server COMA reaches over SSH. It can be a VM at a cloud provider, a home server or bare metal. COMA records its host key, OS, architecture, CPUs, memory, disk and engines.

You need no COMA account and nothing installed on the machine beyond SSH. Docker or Podman can already be there, or coma machine bootstrap can install one.

What COMA recordsCopy Anchor Link

When you add a machine, COMA connects over SSH and stores:

• Target: user, host and port. COMA honours HostName, User, Port and IdentityFile from ~/.ssh/config; values you pass explicitly win.
• Host key: its type and SHA-256 fingerprint.
• Inventory: OS, architecture, CPU count, memory and free space on /.
• Engines: Docker and Podman, with version, socket, Compose, rootless status and health. See Engines.
• Health: healthy, degraded, unreachable or unknown, plus the conditions behind it.

A machine is degraded when, for example, it has no working engine, less than 5 GiB free on /, or a clock that differs from yours by more than 60 seconds. A failing condition comes with a message, and for a missing engine, the command to install one. A machine COMA could not contact is unreachable and keeps its last observed inventory.

Machine names are 1 to 63 characters: letters, digits, ., _ and -. Names are unique regardless of case. COMA also gives every machine an ID that starts with m_. Commands accept either the name or the ID.

Host keysCopy Anchor Link

COMA checks every SSH host key strictly. It never trusts a new key silently.

• If the key is already in your ~/.ssh/known_hosts, COMA uses that entry. It reads that file but never writes to it.
• Otherwise COMA shows the fingerprint and asks you to confirm it. Compare it with the key on the server before you accept.
• Without a terminal (scripts, coding agents, --no-input), pass the fingerprint with --host-key SHA256:…. The error ssh_host_key_unknown tells you which fingerprint the server presented.
• Keys you accept go into COMA's own known-hosts file, which only COMA writes.

If a machine later presents a different key, COMA refuses to connect with ssh_host_key_mismatch. That can mean a reinstalled server or a man-in-the-middle attack. Verify the new fingerprint with the server's owner, then remove the old entry from the file the error names.

Cached and discovered inventoryCopy Anchor Link

Most machine commands read COMA's local state and do not contact the machine. Only discovery connects.

Inventory is a snapshot. If you install an engine or resize the machine outside COMA, run coma machine discover <name> to update it.

LifecycleCopy Anchor Link

coma machine add dev ssh://you@203.0.113.10

machine add connects, verifies the host key and records the inventory. It changes nothing on the machine. Useful flags:

• --identity <file>: a private key to use (repeatable). By default COMA uses ssh-agent, then ~/.ssh/id_*. Passphrase-protected keys need ssh-agent; COMA never asks for or stores a passphrase.
• --host-key SHA256:…: the expected fingerprint, for first use without a terminal.
• --discover=false: record the machine without connecting.
• --label key=value and --description: your own metadata.

The command ends with the next step: coma connect dev, or coma machine bootstrap dev --engine docker when it found no engine.

coma machine bootstrap dev --engine docker --plan

machine bootstrap prepares a machine: it creates COMA's directory (~/.coma) and, with --engine docker or --engine podman, installs that engine from the distribution's own packages. It prints a plan with every command it would run and asks before it changes anything. --plan shows the plan and stops. See Bootstrap a bare VM.

coma machine remove dev

machine remove forgets the machine. The server is not changed. If a context still targets the machine, removal fails with machine_in_use; --detach clears the machine from those contexts in the same step.

Choosing a machineCopy Anchor Link

Commands that need a machine use, in order:

1. --machine <name> on the command;
2. the machine of the current context;
3. otherwise they fail with machine_target_required.

COMA does not pick a machine for you because only one exists. Workspaces add spec.target.machine from coma.yaml between the two.

NextCopy Anchor Link