Machines

Set up with an agentCopy Anchor Link

1. Choose Add Machine in the Mac app.
2. Choose Claude Code or Codex, optionally enter a machine name or address, then choose Start setup.
3. The agent opens in Chat and guides SSH keys and aliases, prerequisites, runtime installation and sign-ins. It explains steps only you can complete, such as passwords, administrator approval and interactive login.
4. After checking the connection and prerequisites, the agent proposes the machine.
5. Review the checks and choose Add machine in Needs You or inline in the agent’s Chat.
6. Airship adds the machine, deploys to it and shows the Machine health checklist. Follow any fix hints, then choose Recheck (⌘R) to run the checks again.

Agents can prepare and propose; only you can add a machine. A proposal does not add a host or deploy anything. Approval rechecks prerequisites and adds the host in Asks first mode. Not now declines; generic Accept All cannot add machines. Failed approvals stay open with an error and hint so you can retry explicitly.

Use an agent elsewhereCopy Anchor Link

Choose Copy setup prompt and paste the brief into an agent on either computer. It explains which computer is the controller and routes SSH configuration and the proposal back there. You can also generate it from the CLI:

airship host setup-prompt worker-ssh --runtime codex

The target hint is optional; use --runtime claude for Claude Code. Generating the brief starts no agent, SSH connection or service. An external agent can submit host propose with --as and poll for your answer. See the setup commands for the proposal and operator-only approval reference.

Connect manuallyCopy Anchor Link

Choose Connect manually in Add Machine to enter the host id, SSH alias, label and permissions. After adding the host, the app keeps the health checklist open for review. Or use the CLI steps below.

Prepare the remote machineCopy Anchor Link

Install Python 3.12+, tmux 3.2+, Git and the agent runtimes you will use. Authenticate Claude Code or Codex on that machine. Keep it awake and reachable while work is running.

Configure noninteractive SSH key authentication from the machine controlling airship. Keep usernames, identity files and connection settings in your SSH config.

ssh -o BatchMode=yes worker-ssh true

Replace worker-ssh with your own alias. This command should exit successfully without asking for a password. Verify the host key through your normal SSH setup before using unattended connections.

Add the hostCopy Anchor Link

airship host check --ssh worker-ssh
airship host add box-a --ssh worker-ssh
airship host ls
airship host check box-a
airship doctor --mesh

host check --ssh checks an alias before registration without changing it. host add deploys airship to the destination. It does not install or sign in to agent runtimes for you. The first argument is airship’s host id; --ssh names the SSH alias.

Start work thereCopy Anchor Link

Use a directory that exists on the destination:

airship start helper --runtime codex --host box-a --cwd /path/to/repo
airship status --host all

Each host has its own permissions and model defaults. New hosts begin in Asks first mode.

Check healthCopy Anchor Link

airship doctor --host box-a
airship doctor --mesh
airship host show box-a

If a host becomes unreachable, airship shows stale information until it can reconnect. Check the machine’s power, network, SSH alias and runtime login before retrying writes.

On Mac hosts, health checks also report system sleep, restart after power loss, wake for network access, FileVault and automatic login. These are advisory; laptops receive information rather than warnings. A user must log in after a restart for Airship’s services to run.