devmachine

CLI Reference

Commands

Every command accepts:

FlagMeaning
--config <dir>the configuration folder to use
--format table|jsonhow to print; JSON is the stable contract
--machine <name>which machine to act on, for commands that act on a server
--helpwhat this command does

devmachine help --json prints the whole tree, including every flag, in one document — read this instead of parsing help text.

setup

devmachine setup [--force] [--no-harden] [--keep-password-login a,b] [--no-essentials] [--no-aliases] [--yes]
                 [--package-manager brew|ports] [--install-prerequisites]

Connects to your server for the first time and gets it ready to use.

With no config.yml yet, it asks for a machine name, an address, the admin account, a port, a domain, and how to log in: a key devmachine makes for itself (recommended), a key file already on your computer, or one your SSH agent holds (for a key in a password manager). Choosing an agent key records its public half as agent_key:, so only that key is offered from then on — never every key the agent holds.

It shows the server’s fingerprint first and asks you to check it against your provider’s dashboard. Say no and nothing is sent or changed.

Then it gets the server ready, in order: try the key; if that fails, ask for the password (never shown on screen); install the key; open a new connection using only the key to prove it works; turn password login off, and ask SSH (sshd -T) that it really is off; install Ansible.

Before password login goes off it asks how: off for every account (the default, Enter), off except for accounts you name, or left as it is. It lists the other accounts people log in with, and on a Mac it says plainly that the change covers every account on it: whoever logs in over SSH with a password today needs a key afterwards. The accounts you keep are written as password_login_keep: on the machine, and ssh_hardening keeps the same exceptions on every sync. Change it later with machines password-login. See password login, account by account. The new machine is written with the essentials package (base, git, firewall, ssh_hardening, caddy and devmachine-app — see what a new machine starts with), so the first sync installs them; --no-essentials leaves it with none. Only a pinned package release that has essentials gets it — an older one starts empty and says so. On a Mac, where essentials does not run, the machine starts with base, devmachine-app and the package manager package instead, and setup says so; with --no-essentials, with the package manager package alone. If the proof step fails, nothing is locked down and the error says where to look. See setting up a server for the first time for why the order matters.

Works on Debian, Ubuntu, Arch Linux and macOS. Before it changes anything it asks the machine what it runs (uname -s, then ID in /etc/os-release, or sw_vers on a Mac). A distribution based on one of them (ID_LIKE), such as Manjaro or Linux Mint, is set up as its base, with a note that it is not tested; anything else is named and it stops, with the machine untouched. See what setup refuses. The password is used once and written nowhere.

On a Mac Ansible comes from a package manager package, mac-brew (Homebrew) or mac-ports (MacPorts), not from the CLI. A machine that lists one keeps it. Otherwise setup adds the one for the manager the Mac already has, and asks when it has neither or both (--package-manager). It copies the package to /opt/devmachine/bootstrap/<package>/, runs its bootstrap check as the admin login, lists what is missing with the time each takes, and installs only after you agree (or with --install-prerequisites). --yes never installs them. See what a machine needs.

Once the machine answers, it asks two more questions: whether to write SSH host entries to ~/.ssh/config (default yes — ssh <workspace>-devmachine and mosh then work from any terminal, and the CLI keeps the entries up to date on its own from then on; see SSH aliases), and whether to reach the machine over Tailscale too (default no — adds the tailscale package; devmachine login tailscale finishes the job, see private networks). A Mac is not asked about Tailscale, since the tailscale package runs only on Linux, and machines add --tailscale says so and adds nothing.

It writes config.yml once the key logs in, before it changes anything on the server. A run that stops earlier — the key refused and no password, the proof failed, nothing answered, the fingerprint declined — writes no config.yml, and with --force leaves the old one as it was. A run that stops later, at root or Ansible, keeps the machine, and running setup again finishes the job. See nothing is written before the key logs in.

With no config.yml yet, it also writes AGENTS.md if none exists, telling a coding agent how to work in this folder — it never overwrites one already there.

FlagMeaning
--forcediscard the existing configuration and start over
--no-hardenleave password login on; the key is still installed and proved
--keep-password-login a,bturn password login off for every account except these, without asking
--no-essentialsstart the machine with no packages, instead of essentials (on a Mac, instead of base and devmachine-app)
--no-aliasesdo not ask about SSH host entries, and do not write them
--yesanswer yes to the SSH host entries question, without asking; never installs prerequisites
--package-manager brew|portson a Mac with neither or both, the package manager to install Ansible with
--install-prerequisiteson a Mac, install what is missing (Command Line Tools, Homebrew or MacPorts, Ansible) without asking

Run again with a configuration in place, and it just makes sure Ansible is installed — it never rewrites config.yml, a key, or SSH settings.

Without a terminal. setup only asks. A script, an agent or an app runs machines add --address … instead: with no config.yml yet it writes the same configuration setup would — the latest packages release pinned, defaults.workspace, the machine with essentials, and AGENTS.md — and runs the same bootstrap. Each question has a flag:

setup asksmachines add flag
machine name--name
address--address
admin login--user
SSH port--port
location (machines add only)--location (left out, external)
domain--domain (only when it writes a new config.yml)
trust this fingerprint?--fingerprint (read it first with machines scan)
how to log in--key new, --key <file> or --key agent:<SHA256:…>
the password--password-stdin
write SSH host entries?yes, unless --no-aliases
reach it over Tailscale?--tailscale
install the agent skills?run devmachine skills add afterwards
which package manager? (a Mac with neither or both)--package-manager brew or --package-manager ports
install what the Mac lacks?--install-prerequisites (--yes never does)

It creates that file only if it is still missing when the bootstrap ends. If another add (or create-local --add) wrote one in the meantime, this machine is added to it instead of overwriting it; a --domain given then is not written, and the output says so.

Only --address does this. machines add with questions and no config.yml stops and sends you to setup, which asks the same questions plus the domain.

Unlike setup, it writes config.yml only once the bootstrap worked, so a run that fails leaves no configuration behind. Workspaces then come from devmachine workspaces new, and packages from devmachine packages add, both without questions when given --yes.

On a self machine (self: true, your own computer — see machines), setup runs the mac-brew package’s bootstrap on your computer (mac-ports when the machine lists it), from the package cache, with no sudo and nothing under /opt. When Homebrew and ansible-playbook are already there it installs nothing and prints <name> is already prepared: ansible-playbook is <path>. Otherwise it lists what is missing and asks first, as on a remote Mac. No fingerprint, key or password involved.

setup git

devmachine setup git [--yes] [--check]

Turns your configuration folder into a git repository, so you can push it to a private remote. config.yml, packages.lock, known_hosts and AGENTS.md are committed — see versioning your configuration for what never is.

In order: writes .gitignore before git init, so a key can never be picked up; git init -b main; commits the files above; checks what got tracked and refuses if a key is already tracked, with the fix; if gh is on PATH and logged in, offers to create a private repo and push.

FlagMeaning
--yesskip local-write questions; never create or push a remote
--checksay what would happen, write nothing

Run again on an existing repository, and it skips straight to the tracked-files check.

doctor

devmachine doctor [--machine m]

Checks whether your machines are healthy and reports what is wrong.

With one machine, or with --machine, it checks that machine. With several machines and no --machine, it checks every one of them, in the order of config.yml, one block each:

machine main:
  pass  configuration       machine "main", 2 address(es), admin root, port 22, 1 workspace(s)
  pass  host key            SHA256:… at 203.0.113.10
  pass  connection          connected through 203.0.113.10
  …

machine laptop:
  pass  configuration       machine "laptop", your computer as a machine, 1 workspace(s)
  …

this computer:
  pass  cli                 0.7.21 is the latest
  pass  packages pin        v17 is the latest

Doctor only reads, so checking all of them is safe; it never guesses which one you meant, because it does not have to. A machine that cannot be reached gets its own fail and does not stop the others.

Six checks in order: configuration, SSH fingerprint, login, operating system (the same check setup makes: Debian, Ubuntu, Arch Linux or macOS, shown as macos 15.7.9), Ansible installed, SSH aliases. A broken fingerprint stops the rest. Then one check per needed credential (credential: <key>) and per installed DNS provider (dns: <provider>).

On a Mac, the Ansible check looks where the bootstrap said ansible-playbook is, then in the Homebrew, MacPorts and pipx folders, since a plain SSH command has none of them on PATH. Then the package manager package’s bootstrap check lists what the Mac lacks: one prerequisite: <name> warning per item (devmachine setup installs it once you agree), or one prerequisites check that passes when nothing is missing, or is skipped when no package manager is chosen yet. The script reaches the Mac on stdin, so doctor leaves nothing on it. Last, one ssh access: <workspace> check per workspace on the Mac: it passes when Remote Login allows all users or the account is in the list, warns when Remote Login allows only some users and the account is not one of them, and is skipped while the account does not exist yet. One SSH command answers for every workspace. See what a machine needs.

A missing or logged-out credential warns, with the fix (devmachine login <credential>, or secrets set then credentials push); so does a DNS provider whose token no longer works. The machine still works; only the tool that needs the login does not. A fail is kept for what makes the machine itself unusable: an invalid configuration, an unknown or changed host key, a machine that cannot be reached, and a missing essential (an unsupported operating system, no Ansible, or, on a self machine, a bundle folder that cannot be written).

The exit code is 0 when every check passed, warned or was skipped, and non-zero only when a check failed — on any machine, when there are several. The error names the machines that failed.

--format json prints the same checks with the same statuses (pass, warn, fail, skip); ok is false only when a check failed. For one machine (or with --machine) the shape is:

{"checks": [{"name": "configuration", "status": "pass", "detail": "…"}, …], "ok": true}

With several machines and no --machine, each machine gets its own entry under machines, and the top-level checks holds only the checks about this computer (cli, packages pin). The top-level ok is false when any check anywhere failed:

{
  "machines": [
    {"machine": "main", "checks": [ … ], "ok": true},
    {"machine": "laptop", "checks": [ … ], "ok": false}
  ],
  "checks": [{"name": "cli", "status": "pass", "detail": "…"}, …],
  "ok": false
}

The SSH aliases check runs only when ssh_aliases: true is set, that is, when devmachine keeps the aliases for you. It runs ssh -G <alias> for each workspace alias — a local lookup, no connection — and compares the hostname, user, port and host key alias against what devmachine aliases would write today. It passes as soon as every alias resolves correctly, whatever file it actually lives in. Otherwise it warns, never fails, naming the alias and what is wrong, with the fix devmachine aliases --write.

With ssh_aliases: false (or left out) it reports skip ssh aliases managed outside devmachine (ssh_aliases: false): you keep ~/.ssh/config yourself, so there is nothing for devmachine to compare it to. It is not reported at all on a self machine — there is no address to write a Host entry for.

Last come two checks about your computer, not the machine: cli (is this the newest CLI release) and packages pin (does config.yml pin the newest packages release). Either one warns when it is behind, with the fix devmachine update, and never fails. When GitHub cannot be reached they report skip. The answers are kept for 6 hours in your cache folder (~/Library/Caches/devmachine on macOS, ~/.cache/devmachine on Linux), so running doctor often does not hit GitHub’s rate limit.

No credential or DNS provider needed is not a failure. A check that could not run reports skip and why — “I cannot tell” is not “it is not there”. A warn is the same idea for something worth fixing that does not mean the machine is broken.

config

devmachine config path      the directory in use, and the rule that chose it
devmachine config show      machines, workspaces and their effective values
devmachine config set <key> <value>   change one setting
devmachine config unset <key>         take it out, so its default applies again

Shows where your configuration lives and what is in it. show validates as it prints, so it is the quickest way to find what is wrong.

With no config.yml yet, show is not an error: it says there is no configuration, and --format json prints {"machines": [], "workspaces": [], "defaults": {"workspace": []}, "credentials": {}}. machines, workspaces and defaults.workspace are always arrays, never null.

defaults.workspace is the package list a new workspace gets (see workspaces). credentials is the top-level answer per login, machine or own; a workspace’s own credentials (in workspaces list --format json) wins over it.

set and unset take the settings of chat, written under chat: in config.yml:

KeyDefaultMeaning
chat.default_workspacethe first workspace, else this computerwhere a new chat runs; local means this computer
chat.folder~/chatsthe folder a new chat runs in, created on first use
chat.harnessclaudeclaude or codex
chat.mcpfalsetrue starts new chats with the account’s MCP servers, hooks and plugins

A value that would not load (a harness other than these, a workspace not in config.yml) is refused and the file is left as it was. show --format json prints them, with their defaults filled in, as "chat": {"default_workspace", "folder", "harness"}.

machines

devmachine machines list                  each machine, its addresses, port, location and workspaces
devmachine machines show [name]           one machine, and what it runs as setup, sync or doctor last read it
devmachine machines add [--location l] [--no-harden] [--keep-password-login a,b] [--no-essentials] [--no-aliases] [--yes] [--package-manager brew|ports] [--install-prerequisites]   set up another server and record it
devmachine machines add --self <name> [--location l] [--package-manager brew|ports] [--install-prerequisites]   add your computer as a machine, with no address
devmachine machines add --name <n> --address <a> --fingerprint <SHA256:…> [--user u] [--port p] [--key new|file|agent:<SHA256:…>] [--location l] [--password-stdin] [--tailscale]   the same, asking nothing
devmachine machines trust [name] [--check] [--replace] [--expect <fp>] [--yes]   check or update its SSH fingerprint
devmachine machines password-login <name> [--off | --keep a,b | --on] [--check] [--yes]   show or change which accounts log in over SSH with a password
devmachine machines scan --address <a> [--port p]   the SSH fingerprint of a server not added yet; writes nothing
devmachine machines edit <name> [--set k=v] [--unset k] [--location l] [--check] [--yes]   change a machine's package settings or location
devmachine machines rm <name> [--yes]     forget a machine; the server keeps running
devmachine machines create-local <name> [--distro ubuntu|arch] [--cpus n] [--memory GiB] [--disk GiB] [--add [--key k] [--no-essentials] [--no-aliases] [--location l]]   a machine on your computer
devmachine machines start <name>          start a local machine
devmachine machines stop <name>           stop a local machine
devmachine machines delete-local <name> [--yes]   destroy it and everything on it

Manages the list of machines devmachine knows about.

With no config.yml yet, list is not an error: it says how to add the first machine, and --format json prints [].

list --format json prints each machine with name, hosts, admin_user, port, key, agent_key, workspaces, packages (the machine’s own package list from config.yml, [] when it has none), location (never empty: external or local when config.yml names none), platform (linux or macos, the names platforms uses in a package.yml, from what a command last read on the machine; macos on your own computer; left out for a machine no command has read yet), and self: true on your own computer. Without --format json, list prints a table with a LOCATION column. config show --format json carries the same machine entries. Your computer is never picked by default — a command with no --machine still acts on the server, even with a self machine also configured.

show prints one machine — the one named, or the one --machine or the configuration picks — with what setup, sync or doctor last read from it: the system, distribution and version, architecture, package manager, init system, where ansible-playbook is, and the PATH prefix run uses. It does not connect; devmachine doctor --machine <name> reads the machine again. devmachine --format json machines show <name> prints the same entry as list --format json, plus observed:

{
  "name": "studio",
  "hosts": ["203.0.113.10"],
  "admin_user": "alice",
  "port": 22,
  "workspaces": [],
  "packages": ["mac-ports"],
  "location": "external",
  "platform": "macos",
  "observed": {
    "observed_at": "2026-10-05T15:22:00-03:00",
    "system": "Darwin",
    "os_family": "Darwin",
    "distribution": "MacOSX",
    "distribution_version": "15.7.9",
    "pkg_mgr": "macports",
    "service_mgr": "launchd",
    "architecture": "x86_64",
    "ansible_playbook": "/opt/local/bin/ansible-playbook-3.14",
    "path_prefix": ["/opt/local/bin", "/opt/local/sbin"]
  }
}

A machine no command has read yet has no observed key. The names follow Ansible’s facts; path_prefix is [] on Linux. Why this lives beside config.yml and not in it: what the CLI knows about a machine.

edit changes a machine’s settings: and nothing else, the way workspaces edit does for a workspace. --set <package>.<name>=<value> writes a package option, read as YAML (--set hostinger.zones=[example.com] writes a list); an empty value or --unset <package>.<name> removes it. Both repeat. A setting for a package the machine does not install is refused, and so is one that does not fit the type its package declares. Comments in config.yml survive, and sync applies the change. --location <text> sets or changes where the machine is; --location "" clears it, back to external (or local for your own computer).

Location. Every machine has one: where it is, such as hostinger, home, office or bedroom. It is trimmed and lowercased, and must be at most 40 letters, numbers, spaces, dots, underscores and hyphens, starting with a letter or number. add asks for it, with external as the default; with --address it takes --location or stays external. add --self and create-local default to local. See where a machine is.

add sets up another server, same as setup — including the SSH aliases and Tailscale questions. add --self <name> instead names the computer devmachine runs on: no address, port or key, and neither question is asked. Refuses if a self machine already exists, or the name is taken. See your computer as a machine for how this differs from machines create-local.

add writes the machine to config.yml only once the key is proved and the bootstrap finished. A run that fails leaves config.yml untouched, so the same command can simply run again — see machines add writes the machine last.

Unattended. --address makes add ask nothing, so a script or an agent adds a machine in one command; every question has a flag, and what is left out takes its default. With no config.yml yet, it writes a new one the way setup does — see setup without a terminal:

FlagDefaultMeaning
--name(required)the machine’s name
--address—an IP, a hostname, or tailscale:<name>
--userrootthe admin login: root, or an account with passwordless sudo
--port22the SSH port
--keynewa key of the CLI’s own for this machine (made, or reused when it exists), a private key file, or agent:<SHA256:…> for a key your SSH agent holds
--fingerprint—the host key to trust on first contact, of any of its types (ED25519, ECDSA, RSA)
--tailscaleoffalso add the tailscale package
--domain—the domain; only when there is no config.yml yet, and refused otherwise
--password-stdinoffread the admin password from stdin, for a server that takes nothing else yet
--keep-password-login—accounts that keep SSH password login when it goes off for everybody else; without it, it goes off for every account
--package-manager—on a Mac with neither or both managers, brew or ports; without it such a Mac stops
--install-prerequisitesoffon a Mac, consent to install what is missing; without it a Mac that lacks something stops

--key agent:SHA256:… picks one key from the SSH agent by its fingerprint (ssh-add -l lists them), the way choosing an agent key does in the questions: its public half is recorded as agent_key:, and only that key is offered from then on. If the agent does not hold it — a locked password manager, another SSH_AUTH_SOCK — add stops before changing anything and lists the fingerprints the agent does hold.

SSH aliases are written unless --no-aliases. --fingerprint is required for a machine not trusted yet: with nobody to ask, trusting whatever answers would be trust on first use with no one looking. Without it, or with a different one, add stops before changing anything and prints the fingerprint it was shown, to check through the provider console or a connection you already trust. machines scan --address <a> shows the same fingerprint before you run add at all.

A key that does not log in yet needs the password once, to install it. With nobody to ask, it comes on stdin: --password-stdin reads all of stdin as the password (only the final line ending is dropped), so it is never in the command line, the shell history or a log:

printf '%s' "$PASSWORD" | devmachine machines add --name box --address 203.0.113.20 \
  --fingerprint SHA256:… --password-stdin

It is used exactly as the interactive password is: one connection that installs the key, then a new connection that proves the key alone, then password login is turned off (unless --no-harden). It is written nowhere. When the key already logs in, the password is never used. Without --password-stdin, a key that does not log in stops add and says so; put the key’s public half in the admin’s authorized_keys first, or pass the password. --password-stdin needs --address: without it, stdin carries the answers to the questions instead.

Adding or removing a machine, like adding or removing a workspace, refreshes the SSH aliases when ssh_aliases: true is set — see SSH aliases.

A self machine has no hosts, user, port or key, and no workspace can live on one. Any command needing a real SSH address — ssh, mosh, tunnel, login, expose, dns, machines trust, aliases — refuses on it, naming the reason.

trust reads the server’s public fingerprint without logging in: asks before saving a new one, does nothing if it matches, refuses a changed one unless --replace. --check compares without writing and reports a changed key instead of refusing it; it exits 0 for every status, so a script reads status, not the exit code. --expect <SHA256:…> writes only the host key with that fingerprint — the key the operator verified, not whatever a second scan happens to meet. It may be the fingerprint of any of the server’s keys, ED25519, ECDSA or RSA: when it is not the one negotiation showed, trust asks the server for each other type and writes the one that matches. A fingerprint none of them has is refused, and nothing is written. JSON fields: machine, address, status (matching, changed, missing), key_type, optional current_key_type and current_fingerprint (the pinned key), presented_fingerprint, check, changed, and, while the key is not yet trusted, fix (the command that trusts it, with --expect) and verify (a command that prints the same key’s fingerprint on the server, to run from its own console).

password-login asks the machine’s sshd, account by account, who can log in over SSH with a password, and changes it. With no flag it only reads. --off turns password login off for every account; --keep a,b turns it off for every account except those; --on takes the CLI’s drop-in away, so the system’s own setting applies again (password login on, on macOS, Debian and Ubuntu). The change goes over the admin login’s key, the proof that a way in stays open. sshd checks the new file before anything uses it, and sshd -T is asked afterwards for every kept account; a file it refuses, or one that does not do what it says, is put back as it was. The kept accounts are written as password_login_keep: on the machine, which ssh_hardening reads on every sync. --on is refused while the machine has ssh_hardening, which would turn it off again. On a Mac it says first that the change covers every account on it. --check says what would change; --yes skips the question. JSON fields: machine, default (password login for an account no exception names), drop_in (whether the CLI’s file is there), accounts (each with user and password_login) and keep (what the configuration says). See password login, account by account.

scan reads the host key a server presents, for an address that is not a machine yet — the step before add --fingerprint, so a person (or an app) can compare it with the provider console before anything trusts it. It does not log in, trusts nothing and writes nothing, and it needs no config.yml. It reports the key the server offers for the same negotiation add makes, so its fingerprint is the one add compares against. JSON fields: address (the one that answered), port, key_type, fingerprint, and verify — a command that prints the same key’s fingerprint on the server, to run from its own console (left out for a key type with no standard file).

rm takes a machine out of config.yml and does nothing to the server itself. Asks first unless --yes; refuses to leave a workspace pointing at a gone machine. It also deletes what the CLI last read from the machine (state/machines/<name>.json). Not delete-local: rm only forgets a server, delete-local erases a machine on your computer.

create-local builds a machine on your computer, arriving password-only like a bought server — devmachine setup still has to run against it. Root password devmachine, public on purpose: this VM holds no real data.

By default the VM gets 2 CPUs, 4 GiB of memory and a 20 GiB disk. --cpus <n>, --memory <GiB> and --disk <GiB> change that, in whole numbers. Each is checked against this computer before Lima starts: --cpus from 1 to its number of cores, --memory from 1 GiB to less than its memory (the computer needs some for itself), --disk at least 10 GiB. The disk is a sparse file, so a large one only uses the space the VM writes. The output says the size the VM got.

--distro picks the system: ubuntu (the default, Ubuntu 24.04) or arch (Arch Linux). The Arch VM is x86_64 under qemu on every computer, because the only aarch64 Arch image Lima offers is an old third-party build that does not boot under Apple’s hypervisor. On Apple Silicon that means emulation: it boots and works, but the first boot and setup take many minutes. It arrives the same way as the Ubuntu one: root by password, no key.

create-local <name> --add does both steps at once: it creates the VM, then adds it the way machines add --address adds a server — installs a key with that password, proves the key, turns password login off, installs Ansible, and writes the machine (and, with no config.yml yet, a new configuration). No second command, and no question. Its host key is trusted as it answers, without --fingerprint: the command made the VM a moment ago and it answers only on this computer’s loopback. --key, --no-essentials, --no-aliases and --location mean what they mean for machines add, and are refused without --add; --location defaults to local here. The name is checked against the configuration before any VM is made. If adding fails, the VM keeps running and nothing is written; the error ends with the exact machines add command that adds it by hand, ready to copy. The host key is read once, and that same key is the one trusted. --format json prints the machine as machines list does, with its key once added, its location and its size (cpus, memory_gib, disk_gib); the progress goes to stderr. start, stop and delete-local only act on a local machine.

Two limits: needs Lima (brew install lima), macOS and Linux only; not reachable from the internet, so dns, HTTPS and subdomains do not work on it.

workspaces

devmachine workspaces list
devmachine workspaces new <name> [--machine m] [--like w] [--packages a,b] [--user u] [--check] [--yes]
devmachine workspaces edit <name> [--machine m] [--user u] [--add p] [--rm p] [--set k=v] [--unset k] [--share c=machine|own] [--check] [--yes]
devmachine workspaces defaults [--add p] [--rm p] [--check] [--yes]   no flag: print the list
devmachine workspaces rm <name> [--yes]
devmachine workspaces destroy <name> [--confirm <name>] [--check] [--keep-dns]

A workspace is one account on one machine. See workspaces.

These commands only edit config.yml — devmachine sync creates or changes the account.

new takes its package list from defaults.workspace: [pkg, ...] in config.yml. --packages overrides it for one workspace; --like <name> copies another workspace’s package list instead — packages only, never the account or the machine.

When the CLI knows the machine’s system (what setup, sync or doctor last read from it), new leaves out of the default or copied list any package that does not run there, itself or through a package it needs, and says which one and why: a workspace on a Mac starts without claude-remote-control, which runs only on Linux. A package named in --packages is refused instead of dropped, since you asked for it by name. edit --add refuses the same way. With the system not yet known, nothing is left out.

defaults with no flag prints that list and changes nothing. With --add or --rm it edits it; existing workspaces keep their own lists. With --format json, both print {"packages": ["dev", "zsh"], "changed": false} — changed is true after an edit, and packages is [] when the list is empty.

list --format json prints {"workspaces": [...]}, one entry per workspace:

{
  "name": "alice",
  "machine": "main",
  "user": "alice",
  "packages": ["workspace", "dev"],
  "settings": {"zsh.theme": "plain"},
  "credentials": {"claude": "own"}
}

user is the account on the machine. packages is [] when there are none, and settings is left out. credentials is the workspace’s own credentials: answer per login — own keeps its own login, machine shares the machine’s — exactly what edit --share writes, and {} when it has none. A login it does not name follows the top-level credentials: (in config show --format json), then the package’s own scope.

new refuses on a machine with no key, since a workspace is reached through the copied admin key. Run devmachine setup first. With several machines, pass --machine.

edit changes one workspace. --add/--rm take a package name each, repeatable. --set <package>.<name>=<value> writes a package option (read as YAML — see packages); an empty value or --unset <package>.<name> removes it. --share <credential>=own keeps this workspace’s own login instead of the shared one; =machine shares it again. A package option for a package the workspace does not install is refused, and so is one that does not fit the type its package declares.

Changing --machine does not move a workspace. The next sync creates the account on the new machine; the old one keeps everything.

rm leaves the account, home and files on the machine — remove those by hand if you want them gone.

new, rm, destroy and edit --machine all refresh ~/.ssh/config’s managed block afterwards, when ssh_aliases: true is set, and say so when it changed. See SSH aliases.

destroy deletes for real: the account, its home, its Caddy routes, and its config.yml entry. Asks you to retype the name first (or --confirm <name> from a script). Needs the machine reachable; use rm for one that is gone. After the account is gone, the DNS record of each of its sites goes too, with the same rules as expose rm: only an A record that still points at the machine serving the site (the via machine for one published through it), through the provider that holds the zone. Anything else is printed, and a DNS failure never stops the destroy. --check also prints those DNS removals. The list it shows before asking names each record it would remove; --keep-dns leaves every one alone instead, and prints the dns rm that removes each later.

defaults only changes defaults.workspace, which new workspaces inherit; existing ones are unchanged.

skills

devmachine skills add [--package name] [--agent claude|codex|opencode|pi|antigravity|kimi|cline] [--yes]
devmachine skills list
devmachine skills update [--yes]
devmachine skills remove <name> [--yes]

Manages Agent Skills on your own computer; never touches a machine.

Bare add installs devmachine-skills from the pinned release (or the latest, before setup has pinned one). --package only accepts a local package. Without --agent, it detects installed agent tools and asks.

list shows each source, its skills and agent tools. update reinstalls every recorded source. remove takes one exact skill name.

Real copy: ~/.agents/skills/<name>. Codex, OpenCode, Pi and Kimi read it there. Claude, Antigravity and Cline get a link to it:

AgentLink
claude~/.claude/skills/<name> -> ../../.agents/skills/<name>
antigravity~/.gemini/antigravity-cli/skills/<name> -> ../../../.agents/skills/<name>
cline~/.cline/skills/<name> -> ../../.agents/skills/<name>

Detection looks for ~/.claude, ~/.codex, ~/.config/opencode, ~/.pi, ~/.gemini/antigravity-cli, ~/.kimi-code and ~/.cline.

widgets

devmachine widgets list [--board home|sidebar|context-sidebar|menubar|menubar-panel]
devmachine widgets help <package/widget>
devmachine widgets validate [path...]
devmachine widgets schema [--json]
devmachine widgets add <package/widget> [--board home|sidebar|context-sidebar|menubar|menubar-panel]
    [--id x] [--set name=value]... [--size s] [--at x,y | --after id | --before id]
devmachine widgets remove <id> [--board home|sidebar|context-sidebar|menubar|menubar-panel]
devmachine widgets move <id> (--after id | --before id) --board sidebar|context-sidebar|menubar|menubar-panel
devmachine widgets set <id> --board home|sidebar|context-sidebar|menubar|menubar-panel
    [--title t] [--every d] [--set name=value]...

The widgets the app draws, and the boards they sit on. Local only: these commands never connect to a machine. See Widgets and the widget format.

list reads the pinned packages release and your own packages. With nothing pinned, or no config.yml yet, it reads the latest release; when that cannot be found it fails, with nothing on stdout. --format json prints:

{
  "engine": "1.7",
  "packages_release": "v40",
  "widgets": [
    {
      "name": "claude-code/usage",
      "package": "claude-code",
      "widget": "usage",
      "origin": "release",
      "trust": "official",
      "version": "v40",
      "path": "/Users/alice/.config/devmachine/cache/packages/v40/packages/claude-code/widgets/usage",
      "summary": "Coding-agent usage windows.",
      "requires_engine": ">= 1.0",
      "fits": ["canvas", "stack", "slot"],
      "context": {},
      "inputs": {"harness": {"type": "string", "default": "claude", "summary": "Which coding agent."}},
      "source": {"kind": "provider", "name": "app/harness-usage", "with": {"harness": "{{inputs.harness}}"}, "every": "60s"},
      "view": {"kind": "app.harness-usage"},
      "sizes": ["small", "medium", "wide"],
      "default_size": "medium",
      "places": ["home"],
      "single": false,
      "surfaces": ["context-sidebar", "home", "sidebar"],
      "available": true,
      "unavailable_reason": ""
    }
  ],
  "providers": {
    "devmachine-app/stats": {
      "package": "devmachine-app",
      "command": "stats",
      "scope": "machine",
      "trust": "official",
      "returns": {"disk": "object", "load": "object", "errors": "list"},
      "min_every": "10s"
    },
    "alice-tools/disk": {
      "package": "alice-tools",
      "command": "disk",
      "scope": "machine",
      "trust": "third-party",
      "package_source": {"url": "https://example.com/alice/tools.git", "ref": "v1", "commit": "0123abc"},
      "returns": {"used": "number"},
      "min_every": "30s"
    }
  },
  "problems": [
    {"path": "/Users/alice/.config/devmachine/packages/mine/widgets/bad/widget.yml", "message": "view.kind \"gauge\" needs engine 1.1"}
  ]
}

origin is release or local; version is the release tag, or "" for your own package. surfaces are the areas the widget fits, planned ones included: the area’s layout is in fits, the widget’s view is drawn there (in the menu bar, only text, number, status and app.brand), and the area gives every context key the widget requires. single is true when a board holds the widget at most once. available is false when the widget needs its package added and synced; unavailable_reason then names the command to run (see why widgets come from packages). A widget with a problem is left out of widgets and listed in problems, and the command still exits 0, so one broken widget never hides the rest. A package.yml that cannot be read is a problem too: its widgets are left out, and when it is one of your own packages the release package of the same name is not used in its place.

trust says how far the app trusts the widget: official for the pinned release, local for a package you wrote in <config>/packages/, and third-party for a package installed with packages install. A third-party widget that runs something — a command, prompt, session or package provider — waits for your approval in the app, like a widget written in a board (see where a public widget comes from). A third-party widget also has package_source: {"url", "ref", "commit"}, where its package was fetched from. When its .devmachine-source.yml cannot be read, the widget is still third-party but has no package_source, and problems says why. A widget that reads a package provider has provider: that provider’s returns and min_every. providers lists every package provider a widget may read, by <package>/<command>, with its package’s scope and trust — a widget written in a board names one of these. A third-party provider has package_source too, the same as its widgets. The app puts that commit in what you approve for a board widget that reads it, so when packages update brings new code the widget asks again.

In the text listing, a third-party widget says (third-party from <url>) in place of its origin.

--board <area> keeps only the widgets whose surfaces include that area — what the app’s gallery offers when you press “Add widget” there. problems are kept as they are.

help prints one widget’s inputs, context, sizes and the areas it fits, and once per board for a single widget; with --format json, the same entry as list. widgets help <widget> describes a widget; --help shows how to use a command.

validate takes a widget.yml, a widget folder, a package folder or a board file. With no path it checks every board in <config>/boards/ and every widget in your own packages. For each widget that passes it prints its full name and the areas it fits (mine/clock fits home); a widget folder that sits in no package’s widgets folder prints its name alone (clock fits home). It reports every problem at once, with file and line, and exits non-zero when there is one. --format json prints {"ok": false, "checked": [...], "widgets": [{"path": ..., "name": ..., "surfaces": [...]}], "problems": [{"path": ..., "line": ..., "message": ...}], "warnings": [...]}, with name written the same way and each warning shaped like a problem.

A widget written in a board that names a machine or a workspace config.yml does not have is a problem. A widget written in a board that reads a package provider is checked too: the package exists and declares it, and every is not below its min_every. With no release in the cache, a missing package is not reported, since it may be one the release has. widgets add, move and remove skip that check, so removing a package never locks a board; they still refuse a provider name that is not <package>/<command> in lower case letters, digits, dashes and underscores. A package widget that names one by its literal name is only a warning (warning: … lines, and "warnings" in --format json), because a published widget is written for many configurations. A name that holds a template, such as {{inputs.machine}}, is not checked. widgets add, move and remove never refuse a name, so removing a machine does not lock a board.

schema prints the engine contract: areas, providers, views and sizes. --json prints it as JSON, the same document the app is built against.

add places a widget on a board and writes <config>/boards/<board>.yml. The id defaults to the widget’s name, made unique (usage, usage-2). --set gives an input a value, converted to the input’s type. For a choice of many, --set machines=main,backup writes a list, and --set machines= an empty one, which means all. A name your config.yml lacks is a warning: on stderr (and in "warnings" with --format json); the widget is still added. The widget must fit the area (devmachine widgets list --board <area> shows which do), and a widget marked single is refused when the board already has it.

On Home (the default), --size is a preset the widget takes or auto. Without it the widget gets auto when its view grows with its content (the summary, machines and coding agent usage views, and the generic text, number, status, list and markdown) and its default_size otherwise. --size auto on a view that does not grow is refused. An auto widget is written as frame: {x, y, w} with no h: w is the width of its default_size, and the app works out the height from the content. The CLI cannot measure, so when it looks for a free spot it counts an auto widget at the height of its default_size (160pt for one written in the board). --at x,y is the top-left corner in points, snapped to 8pt; the widget goes exactly there, even on top of another, because widgets may overlap on Home. Without it the widget takes the first free spot, scanning rows of 8pt from 24,24 across a band 1280pt wide and keeping 8pt from every other widget. --after and --before are refused. The point is on Home with the app’s sidebar open. With the sidebar hidden, the app spreads the widgets over the wider canvas: one at an edge stays at that edge, and any other keeps its share of the space between the edges.

In the sidebar or the Context tab, the widget goes at the end of the list, or right after --after <id>, or right before --before <id> (one of the two at most). --size is a preset or auto; without it the widget gets auto when its view grows with its content and its default_size otherwise. --at is refused. When the board file is missing, the CLI starts from the board the app draws by default, so the workspace list and the Context tab’s sections stay. The default boards are listed in the widget format.

In the menu bar (--board menubar) and its popover (--board menubar-panel), the widget goes in the list the same way, with --after or --before. Neither takes --size or --at. The menu bar holds 3 widgets, so a 4th is refused, and only a widget whose view draws one line fits it. A missing board starts from the default, so ”❯_”, the pull request count and the two tabs stay. See the widget format.

remove takes the widget with that id off the board. On a missing sidebar or menu bar board it starts from the default board, so widgets remove publish-port --board context-sidebar drops that one section and keeps the rest.

move changes a widget’s turn in a list (a sidebar, the menu bar or its popover): right after --after <id> or right before --before <id> (exactly one). --board is required, and Home is refused: a widget there has a place, not a turn. A missing board is read as the default board. A move that leaves the order as it was does not rewrite the file. An empty --after "" or --before "" is refused, on add as on move.

set changes one widget on a board and leaves every other entry as it was. --title is the title this copy shows and --every how often it runs (2m, or manual for any source but a provider); --title "" and --every "" take the override off, so the widget’s own comes back. --every is refused below what the widget’s source allows and on a stream, with the same words as widgets validate. --set gives an input a value as on add, name=a,b for a choice of many. A widget written in the board takes --title only: to change what it runs, edit its source in the board file, and the app asks for your approval again. --board is required; a missing sidebar or menu bar board is read as its default board, and a missing Home board is an error. It prints changed <id> on the <board> board: <what>, then any warning: about a choice your config.yml lacks. A set that changes nothing prints the same line but does not touch the file, so its comments stay.

All four re-read the board first and write it in one step (a temporary file, then a rename). A board with a problem is refused and left as it is; so is a board that changed while the command ran. Comments in a board are lost when the CLI rewrites it. --format json prints {"board", "path", "widget", "warnings"} for add (warnings only when there are some; for a widget in a list, which is a sidebar, the menu bar or its popover, frame, minimized and z are zero and mean nothing, and in the menu bar and its popover size is ""; collapsed appears when true; an auto widget on Home has "h": 0, which means it follows its content), {"board", "path", "removed"} for remove, {"board", "path", "moved", "order"} for move, order being every id after the move, and {"board", "path", "widget", "warnings"} for set.

aliases

devmachine aliases [--write] [--path p] [--check] [--yes]

Prints one SSH Host entry per workspace, so ssh acme-devmachine works from an ordinary terminal, an editor or an app.

# >>> devmachine — generated, do not edit
Host acme-devmachine
    HostName main
    User acme
    Port 22
    ProxyCommand /opt/homebrew/bin/devmachine --config /home/you/.config/devmachine ssh-proxy main %p
    IdentityFile /home/you/.config/devmachine/keys/main
    IdentitiesOnly yes
    HostKeyAlias main-devmachine
    StrictHostKeyChecking yes
    UserKnownHostsFile "/home/you/.config/devmachine/known_hosts"
    GlobalKnownHostsFile /dev/null
    UpdateHostKeys no
    CheckHostIP no
    VerifyHostKeyDNS no
    KnownHostsCommand none
    HostKeyAlgorithms ssh-ed25519
# <<< devmachine

--write puts this block in the aliases’ file, after asking first. Only the text between the two markers is ever replaced — the rest of the file may hold hosts devmachine knows nothing about.

The aliases live in one file: ssh_aliases_path in config.yml, or ~/.ssh/config when that is not set. Every writer uses it — --write, the automatic refresh after a workspace or machine changes, setup and machines add — and so does doctor’s check. --write --path <file> moves them: it writes the block there, records the file as ssh_aliases_path, and empties the block in the file they lived in before, because ssh keeps the first value it reads and a stale copy read first would win. Use it when ~/.ssh/config is generated by something else and Includes a file of its own.

  • ProxyCommand runs ssh-proxy when ssh connects, which picks the first of the machine’s addresses that answers at that moment. The file holds no address, so a private network going up or down never makes it stale. HostName is the machine’s name, and nothing dials it. The path is the devmachine on your PATH, written in full.
  • When devmachine is not on your PATH, the entry has no ProxyCommand, and HostName is the first address that resolves now, as in older versions. Run aliases --write again when that changes.
  • HostKeyAlias is the same for every alias of one machine, so ssh checks the pinned key whichever address it came through.
  • IdentitiesOnly yes goes with IdentityFile, so ssh offers only this key and does not burn login attempts on others in your agent. IdentityFile points at key: when the machine has one, or at the recorded agent_key:’s public file otherwise — ssh matches a public-key IdentityFile against the agent instead of reading a private key from it. With neither, there is no IdentityFile, and ssh offers everything the agent holds.

A -pub alias goes straight to the machine’s first literal address, without ProxyCommand. With ProxyCommand it is written when the machine has more than one hosts entry; without, only when a second address exists and the first did not already resolve to it.

mosh acme-devmachine needs --experimental-remote-ip=remote with the ProxyCommand form: mosh’s default replaces the ProxyCommand with its own. See SSH aliases that resolve when you connect.

--format json adds proxy_command to each alias that has one.

resolve

devmachine resolve [--machine m] [--format json]

Prints the machine’s addresses in the order every connection tries them, without connecting. A <prefix>:<name> entry is asked of the network package that declares the prefix, and a DNS name is looked up, so every address is an IP. An entry that gave no address is listed under skipped, with the reason.

ADDRESS                                  FROM                         PACKAGE
100.64.0.5                               tailscale:main               tailscale
203.0.113.10                             203.0.113.10                 -

skipped:
  tailscale:vps                tailscale is not running

The JSON is what the macOS app reads, and its shape is stable:

{
  "machine": "main",
  "addresses": [
    {"address": "100.64.0.5", "source": "tailscale:main", "package": "tailscale"},
    {"address": "203.0.113.10", "source": "203.0.113.10", "package": ""}
  ],
  "dropped": [
    {"source": "tailscale:vps", "reason": "tailscale is not running"}
  ]
}
  • addresses is in try order. address is always an IP address. source is the hosts entry it came from; package is the network package that resolved it, empty for a literal entry. An entry that gives several addresses appears once per address.
  • dropped is every entry that gave nothing, with why. Both lists are [] when empty, never missing.
  • A tailscale: entry resolved by the deprecated built-in resolver reports "package": "tailscale".

A mosh client needs an IP for its UDP connection: this is where to get it. Refused for a self: true machine, which has no address. See addresses and fallback.

sessions

devmachine sessions [--workspace name]... [--json | --format json]

Prints the tmux sessions of every workspace: name, window count, folder, git branch, age, which coding agents run in it, and whether it is busy or needs attention. It asks all workspaces at once, each with a 5 second limit. --workspace limits the answer to the workspaces you name, and can repeat. A name that is not in the configuration gets its own not-configured error, so one stale name never hides the workspaces that do answer.

WORKSPACE  SESSION   BRANCH            AGE  STATE
alice      checkout  feature/checkout  3h   busy
bob        -         -                 -    error: machine "main": no address answered: ...

--json is the same as --format json. The JSON is what the macOS app reads, and its shape is stable:

{
  "workspaces": [
    {
      "name": "alice",
      "machine": "main",
      "sessions": [
        {
          "name": "checkout-flow",
          "windows": 2,
          "path": "/home/alice/acme-web",
          "branch": "feature/checkout-flow",
          "created_at": "2026-10-08T12:00:00Z",
          "age_seconds": 10800,
          "last_activity_at": "2026-10-08T14:59:58Z",
          "harnesses": ["claude"],
          "busy": true,
          "attention": false
        }
      ]
    },
    {
      "name": "bob",
      "machine": "main",
      "sessions": [],
      "error": {"kind": "unreachable", "message": "machine \"main\": no address answered: ..."}
    }
  ]
}
  • sessions is [] when empty, never missing.
  • error appears only on a workspace that could not answer; the others still answer, and the command exits 0.
  • error.kind is one of unreachable (no address answered, or the 5 seconds ran out), host-key-rejected (the machine’s key is not the one pinned), login-refused (the machine answered but refused the workspace’s login, most often because the workspace is not synced yet, so its account does not exist), login-waiting (the machine accepted the key and the SSH agent has not approved it yet, as 1Password asks after a wake; the login stays open until you approve), tmux-missing (tmux is not installed there), not-configured (the name given to --workspace is not in the configuration) or other.
  • The table shows busy, attention or nothing under STATE, and the folder’s name when a session has no branch.

See session indicators for how busy and attention are decided.

scheduled

devmachine scheduled list [--workspace name]...
devmachine scheduled add --workspace w --name n --folder f
    (--command c | --harness h --prompt p [--model m] [--permission-mode x])
    --every once|hourly|daily|weekdays|weekly|monthly
    [--at HH:MM] [--minute M] [--weekday mon..sun] [--day D] [--date YYYY-MM-DD]
    [--timezone zone] [--timeout 30m] [--allow-dangerous] [--yes]
devmachine scheduled edit <id> --workspace w [any flag of add]
devmachine scheduled pause|resume <id> --workspace w
devmachine scheduled rm <id> --workspace w [--yes]
devmachine scheduled run <id> --workspace w
devmachine scheduled runs <id> --workspace w
devmachine scheduled log <id> <run-id> --workspace w
devmachine scheduled harnesses

A scheduled task runs a shell command, or a prompt for a coding agent, in a folder of a workspace, on a schedule. The workspace keeps and runs its own tasks, so they run with your computer off. See scheduled tasks for how.

devmachine scheduled add --workspace alice --name "Daily briefing" --folder ~/dev/app \
  --harness claude --prompt "Summarize yesterday's commits" --every weekdays --at 09:00
  • --every says how often, and which other flag it needs: once needs --date and --at; hourly needs --minute; daily and weekdays (Monday to Friday) need --at; weekly needs --weekday and --at; monthly needs --day (1 to 31, a short month uses its last day) and --at.
  • --timezone is the zone --at is in, such as America/Sao_Paulo. It defaults to your computer’s.
  • --harness is claude or codex. --model is passed to the agent as written; empty means the agent’s own default. --permission-mode takes the agent’s modes, listed by scheduled harnesses. A mode that never asks for approval needs --allow-dangerous.
  • --folder may start with ~, the workspace’s home. It must exist when the task runs.
  • --timeout stops a run after that long: 30 minutes by default, at most 6 hours.
  • The first task in a workspace without the scheduled package asks to set it up: it adds the package to the workspace and runs sync for its machine, then creates the task. --yes does that without asking. It refuses, and changes nothing, when the packages release your configuration uses has no scheduled package yet.
  • edit changes only the flags you give. Changing --command or --prompt switches what the task runs. Changing --harness drops the old agent’s model and permission mode, unless you give new ones.
  • pause stops a task from running on its schedule; run still runs it. resume refuses a one-off task that already ran; give it a new --date with edit.
  • run starts the task now and prints the run’s id at once. runs shows when it ends, and log what it printed.
  • rm asks first, and deletes the task and the record of its runs.
WORKSPACE  ID        NAME            SCHEDULE           ACTION   NEXT              LAST
alice      t_7f3a9c  Daily briefing  Weekdays at 09:00  claude   2026-10-16 09:00  succeeded 2026-10-15 09:00

With --format json, list prints what the macOS app reads:

{
  "workspaces": [
    {
      "name": "alice",
      "machine": "main",
      "installed": true,
      "tasks": [
        {
          "version": 1,
          "id": "t_7f3a9c",
          "name": "Daily briefing",
          "paused": false,
          "done": false,
          "folder": "~/dev/app",
          "timeout": "30m",
          "schedule": {"every": "weekdays", "at": "09:00", "timezone": "America/Sao_Paulo"},
          "action": {"kind": "prompt", "harness": "claude", "prompt": "Summarize yesterday's commits"},
          "created_at": "2026-10-15T12:00:00Z",
          "updated_at": "2026-10-15T12:00:00Z",
          "next_run_at": "2026-10-16T12:00:00Z",
          "last_run": {
            "id": "20261015T120000Z-ab12",
            "task_id": "t_7f3a9c",
            "status": "succeeded",
            "trigger": "schedule",
            "started_at": "2026-10-15T12:00:00Z",
            "ended_at": "2026-10-15T12:01:10Z",
            "duration_ms": 70000,
            "exit_code": 0
          }
        }
      ]
    },
    {"name": "bob", "machine": "main", "installed": false, "tasks": []}
  ]
}
  • installed is whether the workspace has the scheduled package. A workspace without it is not asked, and has no error.
  • next_run_at is null for a paused task and for a one-off task that is done. last_run is null before the first run.
  • A run’s status is running, succeeded, failed, timeout, error, missed or skipped; message says why when it is not succeeded.
  • error appears only on a workspace that could not answer, and the command still exits 0. error.kind is unreachable, host-key-rejected, login-refused, not-installed (the package is in the configuration but not on the machine yet), outdated (the workspace’s devmachine is older than yours), not-configured or other.

The other commands print, with --format json: add, edit, pause and resume {"workspace", "task"}; rm {"workspace", "removed"}; run {"workspace", "task", "run_id"}; runs {"workspace", "task", "runs"}, newest first; harnesses {"harnesses": [{"name", "package", "permission_modes", "dangerous", "models"}]}. log prints the output as it is.

chat

devmachine chat send [--chat ID] [--workspace W | --local] [--harness claude|codex] [--folder DIR] [--mcp] -- MESSAGE
devmachine chat session (--chat ID | [--workspace W | --local] [--harness claude|codex] [--folder DIR]) [--mcp]
devmachine chat ask (--workspace W | --local) --session S [--folder DIR] [--harness claude|codex] [--chat ID] -- QUESTION
devmachine chat ask (--workspace W | --local) --session S [--folder DIR] [--harness claude|codex] [--chat ID] --serve
devmachine chat list [--all] [--json]
devmachine chat show ID [--json]
devmachine chat rename ID TITLE
devmachine chat delete ID

Talks to the claude or codex you are logged in to, on a workspace or on this computer, read only. See chats for why it runs the CLI and not an API.

send without --chat starts a conversation. The defaults come from chat.harness (claude), chat.default_workspace (else the first workspace, else this computer) and chat.folder (~/chats); set them with config set. With --chat it continues that conversation, on its own harness, workspace and folder. A flag that disagrees with them is an error, printed before any output. send --chat on an ask is refused: an ask goes on with chat ask --chat.

A chat runs without the account’s MCP servers, hooks and plugins, which are most of a harness’s start-up. --mcp turns them on; the choice is kept on the chat, and --mcp=false turns them off again. A new chat without either flag takes chat.mcp (false). See MCP servers are off unless you ask.

ask asks about a coding session without writing to it. --session names the tmux session on the workspace. For a session on this computer that is not in tmux, --folder gives the session’s folder. --harness names the harness when the caller already knows it; otherwise it is read from the session. The first call creates an ask (kind: "ask"); --chat continues it. Every question reads the session’s transcript again and runs the harness with no tools and nothing saved; see asking about a session.

send and ask always print NDJSON, one object per line:

{"type":"started","chat":{...record...}}
{"type":"status","stage":"connecting","message":"Connecting to alice…"}
{"type":"status","stage":"starting","message":"Starting Claude…"}
{"type":"status","stage":"waiting","message":"Claude is thinking…"}
{"type":"text","delta":"It charges "}
{"type":"tool","name":"Read","summary":"acme/billing.go"}
{"type":"text","delta":"in cents."}
{"type":"denied","name":"Edit","summary":"acme/billing.go"}
{"type":"done","chat":{...record...}}
  • started is always the first line, done the last on success.
  • status says what the wait before the answer is spent on, each stage when it really starts, and only the stages that apply: connecting (“Connecting to …”, not for --local), reading-transcript (“Reading the session…”, ask only: finding the session and building its excerpt), starting (“Starting Claude…” or “Starting Codex…”: the harness was launched) and waiting (“Claude is thinking…”: the harness is up, claude’s system/init or codex’s turn.started, and no text came yet). There is no stage for loading MCP servers: claude prints nothing that says it is doing that. A caller clears the status at the first text, tool or denied, and on done or error. status lines are never stored with the messages.
  • On failure the last line is {"type":"error","kind":"…","message":"…"} and the exit code is 1. See the error kinds.
  • text carries the answer as it arrives; claude streams it in small pieces, codex one paragraph at a time.
  • denied is a tool claude wanted and was refused, because a chat has nobody to approve it. They come right before done, one per tool, with the same summary as a tool line. codex reports no such list: a command its sandbox blocks shows only as a tool that failed. See what read only means.
  • SIGINT or SIGTERM stops the harness (on a workspace, the ssh session) and ends with cancelled. The part of the answer that arrived is kept.

chat session and ask —serve

chat session keeps a chat’s harness running and answers messages read on stdin; chat ask --serve does the same for an ask, with questions instead of messages. send stays for scripts. The harness starts before the first message, so a message pays only for its answer; see warm sessions.

Stdin takes one JSON object per line:

{"type":"send","text":"why is the build slow?"}
{"type":"cancel"}

Stdout, one JSON object per line:

{"type":"ready","chat":null}
{"type":"started","chat":{...record...}}
{"type":"text","delta":"…"}
{"type":"done","chat":{...record...}}
{"type":"closed","reason":"eof"}
  • Before ready come the start-up stages: connecting (on a workspace), reading-transcript (--serve without --harness) and starting. Each turn then has its own waiting; ask --serve also reads the session again, with reading-transcript, on every question.
  • ready comes once, when the harness is running. chat is the record for --chat, or null for a new conversation: the first send creates it, and its started carries it.
  • Each send then prints the events of chat send: started, text, tool, denied, then done or error. The process stays running after either. A send that arrives during an answer waits for it.
  • cancel stops the answer that runs; it ends with error cancelled. claude’s process cannot drop an answer, so it is stopped and started again with --resume, and the next message works as before. A cancel with no answer running is ignored.
  • closed is the last line: reason is eof (stdin ended, or SIGINT or SIGTERM), idle (no message for 10 minutes) or error (the harness could not start; an error line with its kind comes first, and the exit code is 1).
  • A line that is not one of the two commands is ignored, with a note on stderr.
  • An unknown flag or command fails before ready with cobra’s own unknown flag or unknown command, which is how a caller tells an older CLI.
  • claude runs as one process for the whole session. codex has no such mode: each message runs codex exec, with resume after the first, and ready comes at once.
  • With --serve, every question still finds the session and reads its transcript again; only the lean harness that answers stays running. When --harness is left out, the session is looked up before ready, and a missing session closes with session-not-found.

A record, as started, done, list and show print it:

{
  "id": "c_3f9a1b2c4d5e",
  "title": "why is the build slow?",
  "harness": "claude",
  "workspace": "alice",
  "folder": "~/chats",
  "harness_session_id": "22222222-aaaa-4bbb-8ccc-000000000001",
  "created_at": "2026-10-15T12:00:00Z",
  "updated_at": "2026-10-15T12:00:09Z",
  "kind": "chat",
  "mcp": false
}
  • workspace is "local" for this computer.
  • mcp says whether the harness runs with the account’s MCP servers.
  • harness_session_id is empty until the harness answered once.
  • title is the first line of the first message, cut to 60 characters.
  • An ask adds session, session_folder (the session’s folder), source_session_id (the id of the transcript the last question read), mode ("transcript") and excerpts (how many pieces of the transcript went into the last question). Its harness_session_id stays empty: an ask keeps no harness session.

list --json prints {"chats": [...]}, the most recently updated first, without asks unless --all. show --json prints {"chat": {...}, "messages": [...]}, each message {"role": "user" | "assistant", "text", "tools": [{"name", "summary"}], "at"}, plus denied: [{"name", "summary"}] on an answer where claude was refused a tool, and error: {kind, message} on an answer that failed. delete forgets the local copy; the harness’s own transcript stays on the workspace.

ssh-proxy

devmachine ssh-proxy <machine> <port>

The ProxyCommand the SSH aliases run; hidden from help. It resolves the machine’s addresses like resolve, connects to the first that accepts a TCP connection on <port>, and passes bytes between ssh (its standard input and output) and the machine until either side closes. Only the connection is retried on the next address — once one answers, the SSH handshake is under way there. When none answers it exits 1 with every address and why on standard error, which ssh shows as the reason the connection closed.

stats

devmachine stats [--machine m]

Prints memory, swap, disk and load. The table rounds; JSON gives raw byte counts. On Linux it reads free, df and /proc/loadavg. A Mac has none of those, so there it reads sysctl, vm_stat and df -k of the data volume; “available” memory is the free, inactive and speculative pages.

ssh, mosh

devmachine ssh [workspace]
devmachine mosh [workspace]

Opens an interactive session: a workspace’s account if named, the machine’s admin if not.

Both run the real ssh/mosh program, so your terminal, agent and tmux behave normally. Both connect to the first address resolve lists. mosh survives a dropped or roaming connection and needs mosh on both sides. Both check <config>/known_hosts first.

run

devmachine run "<command>" [--workspace w] [--no-log]
devmachine run --argv [--workspace w] [--no-log] -- <program> [args...]
devmachine run --package <name> [--workspace w] [--no-log] -- <command> [args...]
devmachine run --package <name> --script <path> [--workspace w] [--no-log] [-- args...]

Runs one command on a machine and prints its output. Its standard output goes to yours and its standard error to yours, as they arrive, so a program can parse stdout (run --package devmachine-app -- stats prints JSON there) while a warning or the reason a command failed still reaches the person, before the error.

--package calls an installed package’s entrypoint directly — everything after -- goes to the package; commands: in its manifest can limit what it accepts. With --workspace, it runs as that workspace’s own account, for a command that needs that account’s own files or logins. Each word after -- reaches the entrypoint as it is, an empty one too: over SSH the command is /bin/sh -s and the words go on its input, so the account’s login shell never reads them. See packages.

--argv runs a program with its arguments exactly as given: each word after -- is quoted before it reaches the machine’s shell, so a space, a ; or a $(…) in one is just a character. It is how the app runs a widget’s command; use it whenever the words come from somewhere else. Over SSH the command is always /bin/sh -s, and the words go on its input, so the account’s login shell — even fish, which reads quotes differently — never sees them. On your own computer (self: true) bash runs the quoted words directly.

--script <path>, with --package, runs one file of the installed package instead of its entrypoint — the copy sync put on the machine, as the same account, with the package’s credential loaded first, the way the entrypoint runs. The path is relative to the package’s package.yml and must stay inside the package. commands: limits only the entrypoint, not a script. Arguments for the script follow --; like --argv, over SSH they go on the input of /bin/sh -s, so the account’s login shell never reads them.

--no-log leaves the run out of the command log. The app uses it for widgets that run every few seconds.

run never sends your input to the command: it reads end-of-file.

Exit code. run exits with the command’s own code: 0 when it worked, the same non-zero code when it ran and failed. A command that ran and failed already said why on its own stderr, so run adds no error: line under it. When the command never ran — no such machine or workspace, no connection, a changed host key, a package that is not installed, a command commands: does not allow — it exits 255, the code ssh uses for the same thing. So 255 has three meanings: the command never ran, the command itself exited 255, or it was stopped (see below). Only the first and the last print an error: line, and that line says which. A mistake in how run was called — an unknown flag, a missing --, a --script path outside the package — exits 1 before anything connects.

Stopping. SIGINT (Ctrl-C) or SIGTERM ends run and the ssh or shell it started, and it exits 255. On your own computer (self: true) the command runs in a process group of its own, and everything it started gets SIGTERM, then SIGKILL five seconds later if it is still there. On a machine reached over SSH, a command that ignores its closed connection, such as an idle tail -f, ends the next time it writes.

run keeps its SSH connection open for five minutes and reuses it, so a script calling it every few seconds skips the handshake each time.

On a machine whose package manager lives outside the system PATH — a Mac with MacPorts or Homebrew — run puts the machine’s path_prefix (see machines show) in front of PATH, so devmachine run 'port installed' finds port the way run 'apt list --installed' finds apt on Debian. A Linux machine has no prefix, and the command goes as written.

upload

devmachine upload <file>... [--workspace w] [--dir path] [--mode 0600]

Sends local files into a home on a machine and prints, one per line, the absolute path each one landed at. With --format json it prints [{"local": "...", "remote": "...", "bytes": N}]; a file that failed has an error field instead of remote.

  • Where. --workspace sends into that workspace’s home, as its own account. Without it, the files go to the home of the machine’s admin, on the machine --machine names, or the only one configured. A workspace and a --machine it does not live on is refused.
  • Folder. ~/.cache/devmachine/uploads by default. --dir names another folder, relative to the home (notes, ~/notes) or absolute inside it (/home/acme/notes). A folder outside the home is refused, and so is one that leaves it through a symbolic link. Missing folders are created, mode 0700.
  • Names. Each file keeps its name, with the local time before the extension: report.pdf becomes report-20260930-143012.pdf, photo.final.png becomes photo.final-20260930-143012.png, and Makefile and .env get it at the end. A name already taken gets -2, -3 and so on: nothing is ever overwritten. Spaces and accents are kept; only /, line breaks and NUL become _.
  • Mode. 0600 unless --mode says otherwise.
  • Failures. A folder, a missing file or one you cannot read is refused before anything connects. With several files, every one is tried; the command exits non-zero if any failed, and names each on stderr.

stdout holds only the paths, so a script or an app can read them. Each upload is one line in the command log. See how an upload lands.

download

devmachine download <remote-path>... [--workspace w] [--to dir] [--progress]

Brings files or folders from a home on a machine to this computer and prints, one per line, the local path each one was saved at. With --format json it prints [{"remote": "...", "local": "...", "bytes": N, "folder": false}]; a path that failed has an error field instead of local.

  • Who reads. --workspace reads as that workspace’s own account, so it gets exactly what that account can read. Without it, the machine’s admin reads, on the machine --machine names, or the only one configured. A workspace and a --machine it does not live on is refused.
  • Which path. Relative to the home (proj/report.pdf), starting with ~/, or absolute (/home/acme/proj/report.pdf). Put -- before a path that starts with -.
  • Where to. ~/Downloads by default. --to names another folder, which must already exist: a typo is refused before anything connects.
  • Names. Each file keeps its name. A name already taken gets -2, -3 and so on before the extension: nothing is ever overwritten.
  • Folders. A folder arrives as one <name>.tar.gz, with the folder at its top. Unpack it with tar xzf <name>.tar.gz, or double-click it in Finder.
  • Failures. With several paths, every one is tried; the command exits non-zero if any failed, and names each on stderr. A failed or cut transfer leaves nothing behind.
  • Progress. --progress writes JSON lines to stderr as each file arrives, about a hundred at most: {"remote": "...", "done": N, "total": N}, with done in bytes. Every path is sized first, so a line with "done": 0 for each one comes before any bytes move. A folder’s total is 0: its archive is packed as it travels. A path that does not exist gets no line.

stdout holds only the paths, so a script or an app can read them. Each download is one line in the command log. See how a download lands.

dns

devmachine dns status [host]
devmachine dns providers
devmachine dns list [zone] [--dns-provider p] [--zone z]
devmachine dns check <name> [--dns-provider p] [--zone z]
devmachine dns add <name> <type> <value> [--ttl s] [--append] [--dns-provider p] [--zone z] [--check] [--publish]
devmachine dns rm  <name> <type> [value] [--dns-provider p] [--zone z] [--check] [--yes]

Manages DNS records through an installed provider package (Hostinger, Cloudflare, GoDaddy). See DNS providers for what differs between them.

status checks a name from the outside — resolves, certificate accepted, answers a request. Defaults to domain. A 4xx counts as serving; a 5xx does not.

providers lists every installed provider and the zones it can see — run first when a DNS command surprised you.

list/check ask the registrar, unlike dns status which asks the public internet. check exits non-zero when a name is not set. --dns-provider picks a provider directly; --zone only for a token that cannot list its own zones. Which provider answered goes to stderr.

add makes a name hold exactly one value, replacing what was there, after showing the zone, provider and value it replaces. --append keeps the values the name holds and adds this one, showing what it sits next to. --ttl sets the seconds a resolver may cache it; without it the registrar chooses. Types: A, AAAA, CNAME, TXT, MX, SRV, NS, CAA, with the value written the way a zone file writes it (10 mail.example.com, 10 5 5060 sip.example.com, 0 issue "ca.example.net"); a value that does not fit its type is refused before any provider is asked. --check previews; --publish is the non-interactive consent (--yes alone never grants it).

rm removes one value, or every value at that name and type with none given — not always one atomic step on the registrar’s side, so it warns first. A name is always the full name (or the zone itself for the apex).

expose

HTTPS only. Caddy handles HTTPS for you; anything else, or anything only you should reach, uses devmachine tunnel instead.

devmachine expose add <workspace> <port> --host <host> [--via <machine>] [--check] [--publish] [--no-apply]
devmachine expose list
devmachine expose rm <host> [--check] [--yes] [--no-apply] [--keep-dns]

Publishes a workspace’s port to the internet, over HTTPS, at a hostname you choose.

add records the site in config.yml, points the hostname at the machine’s first public address in hosts (same as dns add; a private network address listed first is skipped, since visitors cannot reach it), and then puts it on Caddy at once: it writes the workspace’s routes file on the machine and reloads Caddy. That takes seconds, not a whole sync — and it is the very file sync writes, so the next sync has nothing to change. Refuses if caddy is not on the machine. It asks for confirmation first — the port becomes reachable by anyone who learns the hostname; see tunnel for what should not get a yes. --publish is the non-interactive way past that.

  • When Caddy refuses the new file, the old one stays, Caddy’s own error is printed, and the command fails. The route stays in config.yml as pending: fix it and run sync.
  • When the machine cannot be reached, the route is recorded as pending and the command still succeeds. The next sync publishes it.
  • --no-apply only records, the way add worked before: the next sync publishes it.
  • --check changes nothing. It prints the line config.yml would gain and the routes file as it is on the machine against what it would become (+ added, - removed).
  • When a DNS provider refuses the record (a rejected token, a zone it cannot change) or its setup is broken, the site is still put on Caddy: the command says why, prints the record to create by hand, and its JSON carries dns_error.
  • With --format json it prints host, port, workspace, applied (true once Caddy serves it) and status (published or pending), with a note saying why when it is pending. A site published with --via also carries via, and a note when that machine cannot reach the port.
  • --via <machine> publishes through another machine’s Caddy, for a workspace on a machine the internet cannot reach (a VM on your desk, a box behind NAT). The route is recorded with via:, the name points at that machine, and its Caddy proxies to the workspace’s machine at the address its hosts give — one from a private network first, never a loopback one. Without --via, a workspace whose machine has no caddy is refused with the machines that have it. See publishing through another machine.

See why a published app lives in the configuration.

list prints every host the machine’s Caddy serves — those sent to it with --via too, naming the machine they come from — with its port, workspace, and one of four words: published (both agree), pending/differs (needs sync), unmanaged (only the machine has it — adopt with the add shown). Unreachable machine or missing caddy: rows print unknown.

rm takes a host out of the configuration and off Caddy at once, on the machine that serves it whatever --machine says, the same way add puts it on: the workspace’s routes file is written without it (or removed, with no route left) and Caddy reloads. With the machine out of reach it keeps serving the site until the next sync. --no-apply and --check work as for add; in JSON, status is removed or pending. A host the configuration does not know is refused, with how to adopt or remove it by hand.

After Caddy, rm removes the A record add created — through the provider that holds the zone, and only while its value is still the serving machine’s address (the via machine for a site published through one):

  • A record that points somewhere else now is left alone, and the command says where it points. Somebody repointed the name; deleting it would take down whatever answers there.
  • With no provider installed, or the machine out of reach, it prints the record to remove by hand, and the JSON carries dns_error saying so — the record is still there.
  • A name that holds the machine’s address and another value is not deleted through the provider: some providers take one value out by rewriting the whole set, and a failure halfway would take the other value down too. The record to remove by hand is printed, and the JSON carries dns_error.
  • When the provider cannot list the zone or refuses the delete, nothing is deleted, the site still comes off Caddy, the record to remove by hand is printed, and the JSON carries dns_error.
  • The question it asks says so: “Stop publishing https://, and remove its DNS record while it points at ?”.
  • --keep-dns takes the site off Caddy and leaves the record alone, for a name you will point somewhere else yourself. It prints the devmachine dns rm … --machine <machine> that removes it later, and the question no longer mentions DNS.
  • --check also prints the DNS removal it would make.
  • --no-apply touches no machine, so no DNS either: it prints the devmachine dns rm <host> A <address> --machine <serving machine> to run later — --machine names the machine whose DNS provider holds the zone, which is the serving one, not necessarily the only one. (add --no-apply still points the name, since a name that does not resolve yet stops the certificate on the next sync.) See Publishing for the cases this question exists to catch.

tunnel

devmachine tunnel <workspace> <port> [--local <port>]

Opens an SSH tunnel so a remote port shows up as localhost:<port> on your computer. Nothing is published — no DNS, no certificate, no Caddy, only you can reach it.

Use this instead of expose for anything not plain HTTP, or that only you should see: a database tool with real data, an inbox with real mail, a queue dashboard that can drain a queue.

TrafficAnyoneOnly you
HTTPexposetunnel
Anything elsenothingtunnel

--local picks the port on your computer, if the remote one is already taken here. Holds your terminal open while the tunnel is up; Ctrl-C closes it, nothing left running.

machine

devmachine machine setup
devmachine machine doctor

Sets up and checks your own computer — the one thing you still install by hand, once.

doctor checks ssh/mosh on PATH (mosh is a warning only), an SSH agent or configured key, and whether ~/.ssh/config matches what devmachine aliases --write would produce now. That last one runs only with ssh_aliases: true; otherwise it reports skip — you keep the file yourself.

setup installs what is missing via Homebrew on a Mac; on Linux it names what to install instead of guessing. Never installs an editor, shell plugins or language runtimes — that stays your choice.

secrets

devmachine secrets set <name> [value] [--stdin]
devmachine secrets set <name> [value] --workspace w [--env-file path] [--push]
devmachine secrets list [--workspace w]
devmachine secrets rm <name> [--workspace w] [--from-file]
devmachine secrets example

Stores values packages need that are not logins — API keys, tokens.

set with no value asks without echoing, so it never reaches your shell history. list prints names only.

Values go to the OS keychain when there is one, and otherwise to secrets.json in the configuration folder, readable only by you. DEVMACHINE_KEYCHAIN=off skips the keychain and always uses the file — the tests and the acceptance suite set it, so a run never writes to, or prompts about, your own keychain.

example lists which <NAME>= a machine’s packages need, no values, always to stdout — never to a file, since .env.example sits one typo from .env.

A workspace’s own secret

--workspace is a different thing from the plain form above: not a value a package declared, but your own app’s secret — a key your code reads. It stores the value under <workspace>/<name> and delivers it on the next devmachine credentials push, or right away with --push.

By default it lands in ~/.devmachine/env — see the ~/.devmachine/env contract. --env-file <path> delivers into that dotenv file instead, relative to the workspace’s home: the existing <NAME>= line is replaced, or a new one appended, and everything else in the file is left exactly as it was. A path that would reach outside the workspace’s home is refused — here for ../ or an absolute path, and on the machine for a symbolic link that leads out of it. The first time it edits a file that already existed, it keeps a copy at <path>.devmachine.bak. See credentials: your app’s own secrets.

Setting the same name again with a different --env-file (or with none, back to the default) moves it: the next push takes the <NAME>= line out of the file it was in before, then writes it to the new one.

list --workspace w shows only that workspace’s own secrets, with where each is delivered. rm --workspace w --from-file also removes the name from its file, on the next credentials push — it is not edited here, so rm never needs to reach the machine.

The ~/.devmachine/env file

A sourceable file inside every workspace, KEY='value' per line, 0600, owned by the workspace’s own account. It holds every workspace secret delivered with no --env-file. The workspace package makes every shell source it on login (zsh, bash and sh, through ~/.devmachine/shellenv), so exporting anything more is never necessary.

login

devmachine login <credential or network package> [--workspace w] [--machine m]

Runs the login a package declared, in the account it belongs to, over a real terminal session (ssh -t) — a device code or browser prompt has to reach a person.

A workspace credential needs --workspace: no single session to copy between accounts. A machine credential logs in once, as the admin, and copies what the tool wrote to /etc/devmachine/<name>/; the next sync spreads it to workspaces using that package. A kind: secret credential is refused — use devmachine secrets set, then devmachine credentials push.

A network package — one whose package.yml has a network: block with join — is logged in to by its package name: devmachine login tailscale. Instead of a declared command, it runs the package’s join script on the machine, as the admin, over ssh -t, with the machine’s settings for that package (for example tailscale.login_server). Then it runs the package’s self_name script and, unless the machine’s hosts already has it, adds <prefix>:<name> above the other addresses in config.yml, writing hosts: as a block list, one address per line, with any comment next to an address kept. The public address stays as a fallback. When the name cannot be read, it prints the machine’s hosts: block to paste instead, with - <prefix>:<name> first. The package must be synced first: join runs from where sync put it. --workspace is refused: a network joins the machine.

With a packages release whose tailscale package has no network: block yet, login tailscale runs its declared tailscale up, then reads the name from tailscale status --json on the machine and adds tailscale:<name> the same way. This path is deprecated. See private networks and the network package contract.

Same strict fingerprint check as every other command. See SSH: logging in and knowing it is your server.

credentials

devmachine credentials list [--machine m]
devmachine credentials push [--machine m] [--check] [--yes]

Shows what a machine’s packages need to authenticate, and what is missing. Every row names the fixing command. unknown means the package never said where its tool keeps the result — not the same as missing. Never prints a value.

push delivers the values that are missing, and a token it delivered as an env file that the machine holds an older copy of: it asks the machine only for a SHA-256 of that file, so a token rotated with secrets set reaches the machine on the next push (reported as replaced) without a value ever crossing back. A file a tool keeps for itself (path:) is never rewritten once it is there. It skips logins (nobody can push a browser session) and names any secret never stored; exits non-zero if it found one. A workspace’s own value (<workspace>/<name>) wins over the shared one. --check previews and writes nothing.

It also delivers every workspace’s own secret set with secrets set --workspace (see above) whose workspace lives on the machine being pushed to, and removes the ones marked with secrets rm --from-file.

Anything it delivers inside a workspace’s home — a package’s workspace credential or a workspace’s own secret — is refused when a symbolic link on the way leads out of that home, and the file is replaced, never written through, so a link in its place cannot redirect the write.

packages

devmachine packages list
devmachine packages add <name> [--machine m | --workspace w] [--check] [--yes]
devmachine packages rm  <name> [--machine m | --workspace w] [--check] [--yes]
devmachine packages install <git-address>[@<ref>] [--check] [--yes]
devmachine packages update <name> [--check] [--yes]
devmachine packages remove <name> [--yes]
devmachine packages new <name> [--scope machine|workspace] [--into <dir>]
devmachine packages validate <dir>
devmachine packages schema [--json]
devmachine packages help <name> [--json]
devmachine packages pin [release]
devmachine packages outdated

Manages what is installed on your machines and workspaces. See the package format.

add refuses a package that does not run on the machine’s system — or on the system of the workspace’s machine — once the CLI knows that system, so the mistake shows now and not at the next sync. See troubleshooting.

list shows each package once with every machine and workspace that uses it; one nothing provides is listed as missing.

list --format json prints {"release": "v17", "packages": [...]}: release is the packages release the list was read from (empty when nothing is pinned, so only your own packages are listed), and one entry per package:

{
  "name": "hostinger",
  "scope": "machine",
  "source": "release",
  "summary": "DNS zones on Hostinger.",
  "category": "DNS",
  "kind": "dns",
  "platforms": [],
  "needs": [],
  "credentials": [
    {"name": "hostinger", "kind": "secret", "scope": "machine", "env": "HOSTINGER_API_TOKEN", "shareable": false}
  ],
  "variables": [
    {"name": "zones", "summary": "Zones to manage.", "default": [], "type": "list"}
  ],
  "installed_on": ["machine main"]
}

kind is the contract a callable package answers — dns marks a DNS provider — and is left out for an ordinary package. platforms are the operating systems it runs on (linux, macos), and [] means any — a package that says ["macos"] runs only on a Mac machine, one reached over SSH or your own computer as a self machine. needs are the packages it brings in before itself, [] when none: for essentials that is the list it is made of. category is the manifest’s grouping, left out when it has none. credentials lists what the package declares, always an array: each one’s name, kind (secret, file or manual), scope, and env or path where the value is delivered. It never carries a value — it is there so a client knows the name to store with secrets set before the package is added. shareable is true when a workspace can take that login from the machine — workspaces edit --share <name>=machine — because the package says a copy of its session works on another account. When it is false, sync refuses that choice (see troubleshooting), so the only answer is own; it is always false for a secret or a file. variables lists the settings the manifest declares, sorted by name, always an array: each one’s name, summary, the manifest’s default (null when it has none) and type (string, number, boolean, list or map): the one the manifest declares, or else read off the default, and left out when there is neither. It is what --set <package>.<name>=… on machines edit or workspaces edit accepts. It carries the manifest’s default, never a value you set — your values are in workspaces list and config.yml. installed_on is [] when nothing uses the package.

With no config.yml yet, list reads the latest packages release — the one setup would pin — so a new user sees what a first machine can start with. With no network to find it, it fails and says so.

add/rm only edit config.yml — sync applies the change. Pass --machine or --workspace; with one configured machine, that is the target. Comments in config.yml survive.

install brings in a package somebody published in a git repository: https://example.com/alice/tools.git, or [email protected]:alice/tools.git to use your SSH key. @<ref> picks a tag, a branch or a commit; without it, the default branch. Only https:// and git@ addresses are accepted. The repository holds one package, with package.yml at its top.

It fetches that one commit (needs git), checks it the way packages validate does, and refuses:

  • a name the pinned release already has — your package would replace the official one everywhere;
  • a name you already have in <config>/packages/;
  • a link that leads outside the package;
  • a file name, summary, command, provider, credential or needed package holding a character that moves or hides text in a terminal (a control character such as ESC, or a Unicode bidirectional mark or override), or a file name that is not UTF-8;
  • a package that does not validate (every problem is listed).

Then it shows what the package brings — its widgets and which of them run code, the commands of its entrypoint, its providers, every executable file, every task file (tasks/, handlers/), every other file of the role that decides what those tasks do (meta/, library/, module_utils/, *_plugins/, templates/, files/, vars/, defaults/) and the credentials it asks for — and asks before writing <config>/packages/<name>/. --yes does not ask; --check shows and writes nothing. It records where the package came from in <config>/packages/<name>/.devmachine-source.yml:

url: https://example.com/alice/tools.git
ref: v1
commit: 0123456789abcdef0123456789abcdef01234567
installed_at: "2026-10-07T12:00:00Z"

That file is what makes it third-party: its widgets that run code ask before they run (see where a public widget comes from). Installing touches no machine: packages add <name> --machine <m> and sync do, and its tasks then run as root there, like any package’s.

--format json needs --check or --yes, since it cannot ask, and prints {"name", "scope", "summary", "needs", "widgets": [{"name", "source", "runs_code"}], "commands", "providers", "scripts", "tasks", "role_files", "credentials", "url", "ref", "commit", "path", "installed"}.

update fetches the address and ref recorded in .devmachine-source.yml again, checking the address as install does. When the commit did not move it says so and changes nothing. Otherwise it shows the old and new commit; the widgets, commands and providers added or removed; and the credentials, scripts, tasks and role files added, removed or changed (a script, task or role file changed when its bytes did, a credential when anything package.yml says about it did), and asks before replacing the folder (--yes, --check as for install). A new commit changes what the app approved, so the package’s widgets that run code ask again. It refuses a package you wrote yourself, a repository that now holds a package of another name, and a name the pinned release now has. A fetch or a check that fails leaves the old copy as it was: the new one is fetched and checked in a folder beside it, and only then swapped in. --format json prints {"package", "path", "url", "ref", "previous_commit", "commit", "changes": {"widgets_added", "widgets_removed", "commands_added", "commands_removed", "providers_added", "providers_removed", "credentials_added", "credentials_removed", "credentials_changed", "scripts_added", "scripts_removed", "scripts_changed", "tasks_added", "tasks_removed", "tasks_changed", "role_files_added", "role_files_removed", "role_files_changed"}, "updated"}, each an array of names. A Ctrl-C in the middle of the swap can leave the folder missing, with both copies kept under <config>/packages/.install-…/: see troubleshooting.

remove deletes <config>/packages/<name>/ for a package installed with install, after asking. It never deletes a package you wrote, and it refuses one still added to a machine or a workspace: take it off with rm and sync first, or the next sync would find it missing. It also refuses one listed in the future workspace defaults: take it out with workspaces defaults --rm <name> first, or the next workspace would find it missing. Not to be confused with rm, which takes a package off a machine or a workspace and deletes nothing. --format json prints {"package", "path", "removed"}.

new writes a package that already passes validate; refuses to overwrite one that exists. validate reports every problem at once, with file and line. It also prints warnings, which do not fail it: today, a package that reads devmachine_account without registering it (see troubleshooting). --format json adds them as warnings, apart from problems. schema prints the package.yml format this binary reads. pin writes packages: <release> — with none given, the latest; a release is a tag such as v8, never a branch. help asks an installed package what it accepts, by running its own help.

outdated says whether a packages release newer than your pin is out. It changes nothing; devmachine update moves the pin. --format json prints:

{"pinned": "v32", "latest": "v33", "newer": true, "notes_url": "https://github.com/mydevmachine/packages/releases/tag/v33"}

pinned is empty and newer is false when nothing is pinned, or there is no config.yml yet. newer is false when your pin is the newest or newer. notes_url is the release page for latest. The newest release is asked of GitHub at most once a day and kept in your cache folder; update and packages pin ask again and store the answer. Offline, the last answer is used, however old. Offline with no answer ever stored is an error and a non-zero exit (with --format json, nothing on stdout and the error on stderr). Exits 0 whether or not a newer release is out.

sync

devmachine sync [--machine m | --workspace w] [--check] [--yes] [--tags a,b]

Applies your configuration to a machine — installs what is missing, updates what changed.

In order: checks the configuration, fetches the pinned release if needed, plans what the machine and its workspaces should get, checks your own packages, prints the plan, asks, then runs Ansible on the machine, streaming output.

FlagMeaning
--checkdry run: reports what would change, changes nothing
--yesapply without asking
--tags a,bonly the packages named
--workspace wonly that workspace, on the machine it lives on (how)

One tag beyond package names: credentials, which only copies shared logins — run after devmachine login instead of a full sync.

--check never writes the lock file. Only your own packages (in <config>/packages/) are checked before the run. A package installed with packages install whose name the pinned release now has too stops the sync before it connects, since your copy would replace the official one (troubleshooting). Every package’s platforms is checked against the machine’s system before the machine is changed — from what was last read, then again from what sync reads as it connects — and a package for another system stops the sync, naming both (troubleshooting). sync also keeps what it read in <config>/state/machines/<name>.json (see machines show). With --format json, stdout is the result; the plan and machine output go to stderr.

On success, <config>/packages.lock records what was applied, at which release and checksum, for the machine synced. With --tags, it records only the packages named: every other package keeps the entry the last full sync left, and one that never ran stays out of the lock, so run --package and the next sync see what is really there. The files a package added to another’s folder (extends) are recorded only for the packages named, and none of the old ones is forgotten, since the step that removes them did not run. The whole bundle is still sent, so every package’s entrypoint comes from the pinned release. It also refreshes ~/.ssh/config’s managed block, when ssh_aliases: true is set, and prints how to reach each workspace on that machine: devmachine ssh <ws> always, and ssh <ws>-devmachine when aliases are on.

With --workspace, the machine’s own packages and every other workspace are left alone, and so is their part of the lock. It writes extension files and never removes one: the next full sync does that. Naming a --machine the workspace does not live on stops the sync before it connects (troubleshooting).

update

devmachine update [--machine m] [--skip-cli] [--skip-packages] [--yes]
devmachine update --no-machines [--skip-cli] [--skip-packages] [--format json]
devmachine update --cli-only [--format json]

Brings everything up to date, then stops before it changes a machine. Five steps, in order, each with a short header:

  1. CLI — asks GitHub for the newest release. If it is newer: when Homebrew installed the CLI, runs brew update, brew trust --formula (only on a Homebrew that has it) and brew upgrade mydevmachine/tap/devmachine; otherwise downloads the release archive for your system, checks it against the release’s checksums.txt, and swaps it in for the running binary. Then the new binary runs the other steps. A development build (devmachine version says dev) is never replaced.
  2. Packages — when config.yml pins an older packages release, pins the newest, like packages pin. Only config.yml changes (and, in a versioned configuration, one commit). Nothing is pinned when nothing was.
  3. Skills — skills update, for the skills on your computer, from the release just pinned.
  4. Doctor — doctor on every machine (or the one --machine names). Warnings and failed checks are shown, and the run goes on. A machine that cannot be reached skips step 5.
  5. Sync check — sync --check on every machine it reached, and the tasks each one would change. If any would change, it asks once: Apply these changes with sync? [y/N]. Yes runs sync on those machines. No, an empty answer, or no terminal at all prints the exact devmachine sync command to run later.
FlagMeaning
--skip-clileave the CLI as it is
--skip-packagesleave the packages pin as it is
--yesanswer yes to the sync question — this changes machines; use it only in automation you trust
--no-machinesrun steps 1 to 3 and stop: no doctor, no sync check, never a question. It takes --skip-cli and --skip-packages, and refuses --yes, --cli-only and --machine
--cli-onlyrun step 1 alone and stop: no packages pin, skills, doctor or sync, and no configuration is read. It cannot be combined with the other flags or --machine

With --cli-only, a build from source (devmachine version says dev) is an error, not a skip: there is no install to update, so it says what to run instead. With --cli-only --format json, the log goes to stderr and stdout gets one object at the end:

{"from": "0.7.22", "to": "0.7.23", "method": "homebrew", "status": "updated", "ok": true}

method is homebrew, download (the release archive) or source; status is updated, already latest or failed, and a failure adds error with the reason and exits non-zero.

With --no-machines --format json, the log goes to stderr and stdout gets one object at the end:

{"cli": {"from": "0.7.30", "to": "0.7.31", "updated": true}, "packages": {"from": "v32", "to": "v33", "pinned": true}, "skills": {"updated": true}}

Every field is always there. A step that changed nothing has to equal to from and false; so does a skipped one. packages.from is empty when nothing is pinned, and then nothing is pinned. When a step fails, the object is still printed, with what was done, and the command exits non-zero with the reason on stderr. When the CLI was replaced, the object comes from the new binary.

The output ends with one line per step: updated, already latest, ok, nothing to do, skipped or failed, with the reason. The doctor line instead says what doctor found, such as 2 warning(s) or machine far unreachable, and the sync line lists each unreachable machine as far skipped (unreachable).

The exit code is non-zero only when one of update’s own steps failed: the CLI update, the packages pin, the skills, the sync check, or a sync you applied. What doctor finds never fails update; run devmachine doctor when a script needs that exit code. Saying no to the sync is not a failure.

Without --cli-only or --no-machines, update prints for a person, so it refuses --format json; use doctor and sync --check with --format json instead. Why it works this way: Updating.

The hint that a newer packages release is out

After sync, doctor, machines list and workspaces list, a line on stderr says when a packages release newer than your pin is out:

packages v33 is out (you pin v32): run devmachine update

It appears at most once a day, and again on the first run of a new CLI version. It never appears with --format json, when stdout or stderr is not a terminal, or when nothing is pinned. It reads the same daily answer as packages outdated, and asks GitHub at most once a day itself. DEVMACHINE_NO_UPDATE_HINT=1 turns it off.

version, help

devmachine version
devmachine help [command] [--json]

logs

devmachine logs path [--format json]

Prints where the CLI writes its log: <config>/logs/devmachine.log, as an absolute path. With --format json: {"path": "…"}. The path does not change: the macOS app relies on it.

A command that changes a machine (setup, machines add, sync, update, doctor, packages add, run, login, credentials push and the like) writes its whole output there, with secrets taken out, and when it fails its last line on stderr is log: <path>. Any other command writes one line there when it fails, and nothing when it works. See the CLI’s log.

The command log

run, upload, download and sync each append one line to <config>/history.log, mode 0600:

2026-09-18T12:00:00Z  workspace acme   ok      "docker ps"
2026-09-18T12:01:00Z  machine main      failed  "sync --tags caddy"

UTC time, target, success or failure, then the quoted command. See configuration.

run --no-log adds nothing: it is for a program that polls, such as a widget, whose runs would bury everything else.

setup, machines add and login are not logged — the first two handle a root password, and login runs a command you watch yourself.