Getting started
Set up devmachine with a coding agent
This page is for a coding agent — Claude Code, Codex, Cursor or any other — that a person asked to set devmachine up for them. If you are that agent, follow it in order. Talk to the person in their language, ask one question at a time, and never guess an answer only they know.
devmachine sets up a machine for the person to code on: a VPS they rent, a Linux server or a Mac they already have, or a virtual machine on their own computer. The machine runs Debian, Ubuntu, Arch Linux or macOS. Each project gets its own account on that machine, called a workspace, with its own tools, logins and coding agent. devmachine runs on the person’s own computer and reaches the machine over SSH.
Rules
- Your shell has no terminal. A command that asks a question waits
forever for an answer you cannot type. Use the flags this page gives, which
ask nothing, and hand a question-asking command such as
devmachine setupto the person. - Only the person decides what gets installed. On a Mac, setting up may
install the Xcode Command Line Tools, Homebrew or MacPorts, and Ansible.
Ask the person which package manager they want, Homebrew or MacPorts, and
whether devmachine may install what the Mac lacks. Never choose for them.
Pass their answers as
--package-manager brew|portsand--install-prerequisites, and only then.--yesnever means yes to an install. - Only the person confirms a server’s identity. A server shows a code
called the fingerprint. The person checks it against their provider’s
dashboard. Pass
--fingerprintonly after they say it matches; never take it frommachines scanalone, and never answer a fingerprint prompt yourself. - Only the person types a password or signs in to a service. When a step needs one, hand them the command.
- Show before you change a machine. Run
devmachine sync --check, show the person what it will do, and rundevmachine sync --yesonly after they agree. - Use commands, not files. Change the configuration with
devmachinecommands. Never editconfig.ymlby hand. To know where the configuration is, rundevmachine config path— do not guess a folder. - When something fails, read the error, then check troubleshooting, before trying anything else.
1. Install the CLI
Check with devmachine version. If it is missing, run:
curl -fsSL https://mydevmachine.sh/install.sh | sh
On macOS with Homebrew, that installs through the tap
(brew install mydevmachine/tap/devmachine); otherwise it downloads and
verifies the release binary for you.
Then install the skills that teach you the whole CLI, naming your own
coding agent — claude, codex, pi, opencode, antigravity, kimi or
cline:
devmachine skills add --agent claude --yes
Without --agent and --yes it asks a question for each agent it finds, and
you cannot answer it. If your coding agent is none of those, skip this step.
The skills take effect only in a new session, so keep following this page
either way.
2. Ask what you need
First ask: do they have a server, or do they want a machine on this computer? A machine on this computer is free and nothing to buy, a good way to try devmachine; but the internet cannot reach it, so it cannot show an app at a public URL.
Then ask one question at a time.
For a server:
- The server’s address — an IP or a hostname. It must run Debian, Ubuntu, Arch Linux or macOS; ask which.
- How they reach it over SSH: the login, and whether with a key already on the server or with a password. The login is root, or an admin login with passwordless sudo. A Mac has no root login: it needs an admin login with passwordless sudo, and Remote Login on in System Settings > General > Sharing. Only the person can do those two things on a Mac.
- A name for the server, for example
vps. - Where the server is, for example
hostinger,homeoroffice. If they do not say, useexternal. - Only if they want an app visible at a URL: a domain, and whether it is at Hostinger, Cloudflare or GoDaddy. Otherwise skip this.
- Only for a Mac: Homebrew or MacPorts, and whether devmachine may install what the Mac lacks (the Command Line Tools take 5 to 10 minutes). See what a machine needs.
For a machine on this computer:
- A name for it, for example
sandbox: lower-case letters, digits and dashes. - Where it is. A VM on this computer is
local; take another name, such aslaptop, only if they give one.
For both:
- A name for the first workspace, for example the project they will work on.
- Do they want a coding agent inside that workspace? Claude Code is a
package called
claude-code.
3a. A machine on this computer
It needs Lima, which runs the virtual machine. Check
with limactl --version. If it is missing, install it with
brew install lima; without Homebrew, follow
Lima’s install guide.
Tell the person what the machine takes: Ubuntu 24.04 with 2 CPUs, 4 GiB of memory and a 20 GiB disk. The first run downloads the image and boots it, which takes a few minutes. Then run:
devmachine machines create-local <name> --add --location <location>
This creates the VM and adds it in one step, with no questions: it logs in with the VM’s root password (public on purpose — the VM holds nothing real), installs a key, proves it, turns password login off, and writes the machine to the configuration. There is no fingerprint to check here: the VM answers only on this computer, a moment after this command made it.
Go on to step 4.
3b. A server
Read the server’s fingerprint, without logging in and without trusting it:
devmachine machines scan --address <address>
Show the person the SHA256:… it prints and ask them to compare it with
the one in their provider’s dashboard or console. Go on only when they say
it matches.
If their own key already logs in, add the server yourself. Find
the key’s fingerprint with ssh-add -l and pass it as agent:<fingerprint>,
or pass the path of its private key file instead. Pass --user <login> when
the login is not root, as on every Mac:
devmachine machines add --address <address> --name <name> \
--fingerprint SHA256:… --key agent:SHA256:… --location <location> \
[--user <login>] [--domain <domain>]
On a Mac, add the person’s answers: --package-manager brew or
--package-manager ports, and --install-prerequisites only if they said
yes to the install. Without it, a Mac that lacks something stops before
anything is installed, and the error names what is missing.
If only a password logs in, the password must not pass through you.
Hand the person the command, to run themselves after copying the password —
in Claude Code they can type it after ! in this session:
pbpaste | devmachine machines add --address <address> --name <name> \
--fingerprint SHA256:… --location <location> --password-stdin \
[--domain <domain>]
pbpaste is macOS; on Linux, xclip -o -selection clipboard does the same.
Either way, machines add asks nothing: it installs the key (a new one of
the CLI’s own when --key is left out), proves it works, turns off password logins, installs
Ansible (on a Mac, through Homebrew or MacPorts), gives the machine the
essentials package, and writes SSH host entries so
ssh <workspace>-devmachine and mosh work from any terminal and from an
editor like VS Code Remote-SSH. Add --tailscale only if the person wants to
reach the machine over Tailscale too. --domain is accepted only for the
first machine.
--location only says where the machine is, so a view such as the macOS
app’s network map can group machines by place; it changes nothing about how
the CLI reaches it. To change it later, run
devmachine machines edit <name> --location <location>. See
where a machine is.
A person at a terminal of their own can run devmachine setup instead:
it asks the same questions one by one, shows the fingerprint to check, and
on a Mac asks which package manager to use and whether to install what is
missing. That is the right command for a person, not for you.
4. Check the machine
Run devmachine doctor. Every line should pass or warn; fix a warning about
SSH aliases with devmachine aliases --write, and a missing credential with
the devmachine login command it names.
On a Mac, read devmachine --format json doctor --machine <name> before you
run setup again or sync. Each prerequisite: <name> entry of checks[]
is something the Mac still lacks. Tell the person what is missing, ask
before you install it (devmachine setup --install-prerequisites), and name
the steps only they can do: Remote Login, passwordless sudo, and “Allow full
disk access for remote users” when a package needs it.
The machine starts with the essentials package: base tools, git, a
firewall, Caddy, and devmachine-app, what the macOS app reads from a
machine. If they asked for a bare machine, add --no-essentials to
create-local --add or machines add; if they then use the macOS app, add
it alone with devmachine packages add devmachine-app --machine <name>.
essentials, firewall and caddy run on Linux only, and sync refuses
them on a Mac before it changes anything. You do not need to do anything
about it: when machines add finds a Mac, it starts it with base,
devmachine-app and the package manager package (mac-brew or
mac-ports) instead of essentials, and says so. With --no-essentials
it starts with the package manager package alone.
5. Create the workspace
devmachine workspaces new <workspace>
devmachine packages add claude-code --workspace <workspace>
devmachine sync --check
Skip the claude-code line if they wanted no coding agent. With more than
one machine configured, add --machine <name> to each of these. Show them
the plan, and once they agree run devmachine sync --yes. The first sync
takes a few minutes.
6. Sign in to GitHub
If they use GitHub, hand them devmachine login gh. It opens a terminal on
the machine with GitHub’s own sign-in page, which only they can finish. Then
run devmachine sync --yes, which copies that login into every workspace
that uses GitHub.
7. Hand it back
Tell them to enter the workspace with devmachine ssh <workspace>, or with
ssh <workspace>-devmachine from any terminal or editor. If they asked for a
coding agent, they run claude there once to sign in.
Offer what they may want next, each in one short line:
guides — a site with its own domain and HTTPS, a
Docker app, Claude Code opened from the phone, an agent in its own workspace.
On a machine on this computer, an app is seen through
devmachine tunnel <workspace> <port> instead of a URL.