Getting started
Getting started
devmachine sets up a machine for you to code on: a VPS you rent, or a Linux box or Mac you already have. Each project or client gets its own account on the machine, called a workspace, with its own tools and logins.
You need a machine running Debian, Ubuntu, Arch Linux or macOS that you
reach over SSH as root, or as an admin login with passwordless sudo, and a
Mac or Linux computer to run the CLI. A Mac as the machine needs Remote
Login on; setup asks whether to use Homebrew or MacPorts, and asks before
it installs anything. See what a machine needs.
Pick how to start. Both end in the same place: the CLI installed, your server connected, and a workspace to code in.
- With the macOS app — a window walks you through it. macOS 14 or later.
- With the CLI — three commands in a terminal. Mac or Linux.
With the macOS app
-
Download Devmachine.dmg, open it, and drag Devmachine to Applications. With Homebrew:
brew install --cask mydevmachine/tap/devmachine-app. -
Open Devmachine and click Set up devmachine. It installs the CLI, then runs
devmachine setupin a terminal inside the window: give it your server’s address, check the fingerprint, and say yes to the SSH host entries (the app connects through them). Then it adds thedevmachine-apppackage to the server and runssync. You see every command as it runs. -
When it says Devmachine is ready, click Restart Devmachine.
-
Create your first workspace from any terminal:
devmachine workspaces new acme && devmachine syncIt shows up in the app’s sidebar. Click it to open a terminal in it. The session grid shows all the sessions of a workspace side by side.
A step failed? Click Try again, or, if a coding agent such as Claude Code or Codex is on your Mac, ask it to fix the step for you. More about the app: mydevmachine.sh/app.
With the CLI
curl -fsSL https://mydevmachine.sh/install.sh | sh
devmachine setup
devmachine workspaces new acme && devmachine sync
On macOS, that line installs through Homebrew if you have it. Prefer
Homebrew directly? brew install mydevmachine/tap/devmachine works the same
way.
No server yet? Make a machine on your computer instead, with
Lima (brew install lima), and use it in place of
setup:
devmachine machines create-local sandbox --add
It creates a virtual machine and adds it in one step. See try it on your own computer first.
devmachine skills add teaches your coding agent how to use devmachine. You
can run it before setup, too.
Then work in your new workspace:
devmachine ssh acme
setup also asks whether to write SSH host entries for you. Say yes, and
ssh acme-devmachine works from any terminal, editor or app that dials ssh
directly — VS Code Remote-SSH, Zed, the macOS app. For mosh, use
devmachine mosh acme. See reaching your server.
What each command does
setup asks for your server’s address. It shows a code called the
fingerprint: check it matches the one in your provider’s dashboard, so you
know you are talking to your own server. Then it sets up a key and turns off
password logins, so only you can get in.
setup also gives the server the essentials package: base tools, git, a
firewall, SSH with passwords kept off, Caddy to publish sites with HTTPS,
and what the macOS app reads from a server. Docker is not in it; add it with devmachine packages add docker when
you need it. Want a bare server instead? Run devmachine setup --no-essentials. On a Mac, where essentials does not run, it starts
with base, devmachine-app and mac-brew or mac-ports instead.
workspaces new acme creates a workspace called acme. sync builds it
all on the server.
Set up before the essentials existed? Add them to the server you already have, nothing to rebuild. What is already installed stays as it is:
devmachine packages pin
devmachine packages add essentials
devmachine sync
packages pin moves you to the latest set of packages, the first one with
essentials in it. On a Mac, add base and devmachine-app instead:
sync refuses essentials there.
A new workspace comes with git, the GitHub CLI, Node LTS (through mise), bun,
and zsh with Oh My Zsh. Every SSH login lands in a tmux session, so a dropped
connection loses nothing: connect again and you are back where you were. Turn
that off with the zsh.tmux_auto_attach setting. The server itself gets
only the packages you add to it.
Something failed? Troubleshooting says what each error really means.
Set it up to develop
- A coding agent:
devmachine packages add claude-code --workspace acme, thendevmachine sync. - GitHub, signed in once for every workspace:
devmachine login gh, thendevmachine sync. See credentials. - Docker:
devmachine packages add docker, then let the workspace use it withdevmachine workspaces edit acme --set 'workspace.groups=[docker]', thendevmachine sync. - Anything else:
devmachine packages listshows what is available. Packages says how to add one or write your own. - Teach your coding agent this CLI:
devmachine skills add. See agent skills.
Extras
- Show an app at a URL — anything listening on a port, a dev server or a
Docker container. Add a reverse proxy once with
devmachine packages add caddyanddevmachine sync, thendevmachine expose add acme 3000 --host app.example.computs it on Caddy in seconds. To reach it only from your own computer, with no public URL, usedevmachine tunnel acme 3000instead. See publishing. - Keep your configuration in git:
devmachine setup git. See versioning your configuration.
Real setups, step by step: guides.