CLI Reference
Commands
Every command accepts:
| Flag | Meaning |
|---|---|
--config <dir> | the configuration folder to use |
--format table|json | how to print; JSON is the stable contract |
--machine <name> | which machine to act on, for commands that act on a server |
--help | what 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.
| Flag | Meaning |
|---|---|
--force | discard the existing configuration and start over |
--no-harden | leave password login on; the key is still installed and proved |
--keep-password-login a,b | turn password login off for every account except these, without asking |
--no-essentials | start the machine with no packages, instead of essentials (on a Mac, instead of base and devmachine-app) |
--no-aliases | do not ask about SSH host entries, and do not write them |
--yes | answer yes to the SSH host entries question, without asking; never installs prerequisites |
--package-manager brew|ports | on a Mac with neither or both, the package manager to install Ansible with |
--install-prerequisites | on 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 asks | machines 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.
| Flag | Meaning |
|---|---|
--yes | skip local-write questions; never create or push a remote |
--check | say 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:
| Key | Default | Meaning |
|---|---|---|
chat.default_workspace | the first workspace, else this computer | where a new chat runs; local means this computer |
chat.folder | ~/chats | the folder a new chat runs in, created on first use |
chat.harness | claude | claude or codex |
chat.mcp | false | true 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:
| Flag | Default | Meaning |
|---|---|---|
--name | (required) | the machine’s name |
--address | — | an IP, a hostname, or tailscale:<name> |
--user | root | the admin login: root, or an account with passwordless sudo |
--port | 22 | the SSH port |
--key | new | a 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) |
--tailscale | off | also add the tailscale package |
--domain | — | the domain; only when there is no config.yml yet, and refused otherwise |
--password-stdin | off | read 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-prerequisites | off | on 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:
| Agent | Link |
|---|---|
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.
ProxyCommandrunsssh-proxywhen 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.HostNameis the machine’s name, and nothing dials it. The path is thedevmachineon yourPATH, written in full.- When
devmachineis not on yourPATH, the entry has noProxyCommand, andHostNameis the first address that resolves now, as in older versions. Runaliases --writeagain when that changes. HostKeyAliasis the same for every alias of one machine, so ssh checks the pinned key whichever address it came through.IdentitiesOnly yesgoes withIdentityFile, so ssh offers only this key and does not burn login attempts on others in your agent.IdentityFilepoints atkey:when the machine has one, or at the recordedagent_key:’s public file otherwise — ssh matches a public-keyIdentityFileagainst the agent instead of reading a private key from it. With neither, there is noIdentityFile, 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"}
]
}
addressesis in try order.addressis always an IP address.sourceis thehostsentry it came from;packageis the network package that resolved it, empty for a literal entry. An entry that gives several addresses appears once per address.droppedis 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: ..."}
}
]
}
sessionsis[]when empty, never missing.errorappears only on a workspace that could not answer; the others still answer, and the command exits 0.error.kindis one ofunreachable(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--workspaceis not in the configuration) orother.- The table shows
busy,attentionor nothing underSTATE, 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
--everysays how often, and which other flag it needs:onceneeds--dateand--at;hourlyneeds--minute;dailyandweekdays(Monday to Friday) need--at;weeklyneeds--weekdayand--at;monthlyneeds--day(1 to 31, a short month uses its last day) and--at.--timezoneis the zone--atis in, such asAmerica/Sao_Paulo. It defaults to your computer’s.--harnessisclaudeorcodex.--modelis passed to the agent as written; empty means the agent’s own default.--permission-modetakes the agent’s modes, listed byscheduled harnesses. A mode that never asks for approval needs--allow-dangerous.--foldermay start with~, the workspace’s home. It must exist when the task runs.--timeoutstops a run after that long: 30 minutes by default, at most 6 hours.- The first task in a workspace without the
scheduledpackage asks to set it up: it adds the package to the workspace and runssyncfor its machine, then creates the task.--yesdoes that without asking. It refuses, and changes nothing, when the packages release your configuration uses has noscheduledpackage yet. editchanges only the flags you give. Changing--commandor--promptswitches what the task runs. Changing--harnessdrops the old agent’s model and permission mode, unless you give new ones.pausestops a task from running on its schedule;runstill runs it.resumerefuses a one-off task that already ran; give it a new--datewithedit.runstarts the task now and prints the run’s id at once.runsshows when it ends, andlogwhat it printed.rmasks 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": []}
]
}
installedis whether the workspace has thescheduledpackage. A workspace without it is not asked, and has no error.next_run_atisnullfor a paused task and for a one-off task that isdone.last_runisnullbefore the first run.- A run’s
statusisrunning,succeeded,failed,timeout,error,missedorskipped;messagesays why when it is notsucceeded. errorappears only on a workspace that could not answer, and the command still exits 0.error.kindisunreachable,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-configuredorother.
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...}}
startedis always the first line,donethe last on success.statussays 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…”,askonly: finding the session and building its excerpt),starting(“Starting Claude…” or “Starting Codex…”: the harness was launched) andwaiting(“Claude is thinking…”: the harness is up, claude’ssystem/initor codex’sturn.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 firsttext,toolordenied, and ondoneorerror.statuslines 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. textcarries the answer as it arrives; claude streams it in small pieces, codex one paragraph at a time.deniedis a tool claude wanted and was refused, because a chat has nobody to approve it. They come right beforedone, one per tool, with the samesummaryas atoolline. codex reports no such list: a command its sandbox blocks shows only as atoolthat 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
readycome the start-up stages:connecting(on a workspace),reading-transcript(--servewithout--harness) andstarting. Each turn then has its ownwaiting;ask --servealso reads the session again, withreading-transcript, on every question. readycomes once, when the harness is running.chatis the record for--chat, ornullfor a new conversation: the firstsendcreates it, and itsstartedcarries it.- Each
sendthen prints the events ofchat send:started,text,tool,denied, thendoneorerror. The process stays running after either. Asendthat arrives during an answer waits for it. cancelstops the answer that runs; it ends witherrorcancelled. claude’s process cannot drop an answer, so it is stopped and started again with--resume, and the next message works as before. Acancelwith no answer running is ignored.closedis the last line:reasoniseof(stdin ended, or SIGINT or SIGTERM),idle(no message for 10 minutes) orerror(the harness could not start; anerrorline 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
readywith cobra’s ownunknown flagorunknown 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, withresumeafter the first, andreadycomes at once. - With
--serve, every question still finds the session and reads its transcript again; only the lean harness that answers stays running. When--harnessis left out, the session is looked up beforeready, and a missing session closes withsession-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
}
workspaceis"local"for this computer.mcpsays whether the harness runs with the account’s MCP servers.harness_session_idis empty until the harness answered once.titleis 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") andexcerpts(how many pieces of the transcript went into the last question). Itsharness_session_idstays 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.
--workspacesends 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--machinenames, or the only one configured. A workspace and a--machineit does not live on is refused. - Folder.
~/.cache/devmachine/uploadsby default.--dirnames 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, mode0700. - Names. Each file keeps its name, with the local time before the
extension:
report.pdfbecomesreport-20260930-143012.pdf,photo.final.pngbecomesphoto.final-20260930-143012.png, andMakefileand.envget it at the end. A name already taken gets-2,-3and so on: nothing is ever overwritten. Spaces and accents are kept; only/, line breaks and NUL become_. - Mode.
0600unless--modesays 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.
--workspacereads 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--machinenames, or the only one configured. A workspace and a--machineit 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.
~/Downloadsby default.--tonames 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,-3and 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 withtar 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.
--progresswrites JSON lines to stderr as each file arrives, about a hundred at most:{"remote": "...", "done": N, "total": N}, withdonein bytes. Every path is sized first, so a line with"done": 0for each one comes before any bytes move. A folder’stotalis0: 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.ymlaspending: fix it and runsync. - When the machine cannot be reached, the route is recorded as
pendingand the command still succeeds. The nextsyncpublishes it. --no-applyonly records, the wayaddworked before: the nextsyncpublishes it.--checkchanges nothing. It prints the lineconfig.ymlwould 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 jsonit printshost,port,workspace,applied(trueonce Caddy serves it) andstatus(publishedorpending), with anotesaying why when it is pending. A site published with--viaalso carriesvia, and anotewhen 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 withvia:, the name points at that machine, and its Caddy proxies to the workspace’s machine at the address itshostsgive — 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_errorsaying 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-dnstakes the site off Caddy and leaves the record alone, for a name you will point somewhere else yourself. It prints thedevmachine dns rm … --machine <machine>that removes it later, and the question no longer mentions DNS.--checkalso prints the DNS removal it would make.--no-applytouches no machine, so no DNS either: it prints thedevmachine dns rm <host> A <address> --machine <serving machine>to run later —--machinenames the machine whose DNS provider holds the zone, which is the serving one, not necessarily the only one. (add --no-applystill points the name, since a name that does not resolve yet stops the certificate on the nextsync.) 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.
| Traffic | Anyone | Only you |
|---|---|---|
| HTTP | expose | tunnel |
| Anything else | nothing | tunnel |
--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.
| Flag | Meaning |
|---|---|
--check | dry run: reports what would change, changes nothing |
--yes | apply without asking |
--tags a,b | only the packages named |
--workspace w | only 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:
- 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) andbrew upgrade mydevmachine/tap/devmachine; otherwise downloads the release archive for your system, checks it against the release’schecksums.txt, and swaps it in for the running binary. Then the new binary runs the other steps. A development build (devmachine versionsaysdev) is never replaced. - Packages — when
config.ymlpins an older packages release, pins the newest, likepackages pin. Onlyconfig.ymlchanges (and, in a versioned configuration, one commit). Nothing is pinned when nothing was. - Skills —
skills update, for the skills on your computer, from the release just pinned. - Doctor —
doctoron every machine (or the one--machinenames). Warnings and failed checks are shown, and the run goes on. A machine that cannot be reached skips step 5. - Sync check —
sync --checkon 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 runssyncon those machines. No, an empty answer, or no terminal at all prints the exactdevmachine synccommand to run later.
| Flag | Meaning |
|---|---|
--skip-cli | leave the CLI as it is |
--skip-packages | leave the packages pin as it is |
--yes | answer yes to the sync question — this changes machines; use it only in automation you trust |
--no-machines | run 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-only | run 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.