devmachine

CLI Reference

Settings

Every variable the published packages accept, and what each one defaults to.

A setting is written <package>.<name> under a machine’s or a workspace’s settings:, and it reaches the recipe as the variable it already reads. A setting is a default somebody overrode, not a new mechanism — the recipe cannot tell the difference and does not have to.

machines:
  - name: main
    packages: [base, caddy]
    settings:
      base.timezone: Europe/Lisbon
      caddy.email: [email protected]

Or without opening the file:

devmachine workspaces edit alice --set zsh.tmux_config=false
devmachine machines edit main --set [email protected]

A setting for a package the target does not install is refused. A typo in a package name would otherwise be silent: the value would reach nothing, the recipe would keep its default, and the machine would not be what the configuration says it is.

This page is generated by make settings. Do not edit it by hand.

SettingWhat it doesDefault
antigravity.homeWhere the account’s home is.<the account's own home>
base.hostnameThe machine’s hostname. Empty leaves the one it already has.(empty)
base.swapSize of a swapfile at /swapfile, such as 8G. Empty leaves the machine alone. Nothing on macOS, which manages its own swap.(empty)
base.timezoneThe machine’s timezone, as tzdata spells it. Empty leaves whatever the machine came with.(empty)
base.upgradeUpgrade every package already installed. Off, because that is the owner’s decision and not a side effect of installing base tools. On Arch Linux it is also the only thing that refreshes the package lists. Nothing on macOS.false
caddy.emailThe address the certificate authority writes to about an expiring certificate. Empty means an anonymous account.(empty)
caddy.local_certsSign certificates locally instead of asking Let’s Encrypt. For a machine no name resolves to — a test VM, a private network — where the ACME challenge can never succeed. Off, because a certificate nobody else trusts is not what a public site wants.false
caddy.siteServe a one-page site straight from Caddy, no container behind it. It answers 200, which proves the name, the certificate and the proxy in one request. Off leaves the machine serving only what other packages add.true
caddy.site_domainThe name the one-page site answers to, with its own certificate. Empty serves it on port 80 at the machine’s address, over plain HTTP, because no public authority signs a certificate for a bare address. It creates no DNS record: pointing the name is devmachine dns add.(empty)
caddy.sourceWhere Caddy is installed from. auto uses Caddy’s apt repository and, when apt cannot check that repository’s signature, installs the pinned GitHub release instead. apt uses only the repository and fails when it cannot be checked. github always installs the pinned GitHub release and removes the repository. Debian and Ubuntu only: elsewhere Caddy comes from the system’s own repository, and on macOS from Homebrew or MacPorts.auto
caddy.versionThe Caddy release installed from GitHub, by source: github or by the auto fallback. The .deb is checked against the release’s own sha512 checksums before it is installed. The apt repository, and every system other than Debian and Ubuntu, ignores it.2.11.4
claude-code.diff_sidebarOpen the /diff panel. Unset leaves whatever Claude Code has. It is a preference Claude Code keeps in its own state file, so it is amended only where that file, and that preference, already exist.(none)
claude-code.envEnvironment variables every Claude Code session runs with, as a map. It is how a model-specific or terminal-specific workaround is turned on without this package having an opinion about it.map[]
claude-code.expanded_todosShow the task list under the footer. Unset leaves whatever Claude Code has, and the same condition applies.(none)
claude-code.homeWhere the account’s home is.<the account's own home>
claude-code.remote_control_at_startupConnect every session to Remote Control as it opens, instead of waiting for somebody to type /rc.false
claude-code.session_name_prefixWhat each Remote Control session is called in the phone app. Empty means the workspace’s name, which is what tells two workspaces’ sessions apart.(empty)
claude-code.status_lineThe command Claude Code runs to draw its status line. Empty leaves the status line alone. It runs outside a login shell, so give it an absolute path.(empty)
claude-plugins.claudeWhere the Claude Code CLI is. It is installed into the account’s own ~/.local/bin, so only a workspace that put it somewhere else says so.<the home>/.local/bin/claude
claude-plugins.homeWhere the account’s home is.<the account's own home>
claude-plugins.marketplaceWhere the plugins come from: a GitHub repository written owner/name, a git URL, or a path on the machine. Empty installs nothing.(empty)
claude-plugins.pluginsWhich plugins to install, each written @. The marketplace half is the name the marketplace gives itself, which is what Claude Code installs and reports against.[]
claude-plugins.updateRe-fetch the marketplace and update every plugin on each run. It is off by default because it cannot tell whether anything moved, so a run with it on always reports a change.false
claude-remote-control.homeWhere the account’s home is.<the account's own home>
claude-remote-control.restart_secondsHow long to wait before reconnecting. The server gives up on its own after about ten minutes with no network, so the unit restarts for good. On macOS it is launchd’s ThrottleInterval.30
claude-remote-control.session_nameWhat this session is called in the phone app. Empty means the workspace’s name, which is what tells two workspaces’ sessions apart.(empty)
claude-remote-control.working_directoryThe directory a remote session starts in.<the home>/dev
cline.homeWhere the account’s home is.<the account's own home>
codex.homeWhere the account’s home is.<the account's own home>
dev.gh_versionWhich GitHub CLI release to install. It is a release asset rather than a distribution package because most distributions do not carry gh at all.2.63.2
dev.homeWhere the account’s home is.<the account's own home>
dev.node_versionWhich Node mise installs globally.lts
devmachine-app.github_hostsGitHub Enterprise hosts the context panel resolves pull requests on, each as {host, proxy} with proxy optional. github.com always works; this adds more.[]
docker.vm_cpusmacOS only. The CPUs each workspace’s VM gets.2
docker.vm_memorymacOS only. The memory each workspace’s VM gets, in GiB.2
docker.workspacesmacOS only: the workspaces that get a Docker VM of their own. Empty means every workspace on the machine.[]
fail2ban.bantimeHow long a ban lasts, in seconds.3600
fail2ban.ignoreipThe addresses that are never banned, space separated. Loopback only by default: a wider range exempts everyone who shares it.127.0.0.1/8 ::1
fail2ban.maxretryHow many failures from one address before it is banned.5
firewall.httpOpen 80 and 443. A machine that hosts nothing can turn this off.true
firewall.mosh_interfaceThe one interface mosh’s UDP range is opened on. Empty means it is not opened at all, which keeps the range off a public edge.(empty)
firewall.mosh_portsThe UDP range mosh is given on that interface.60000:61000
git-key.homeWhere the account’s home is.<the account's own home>
glab.homeWhere the account’s home is.<the account's own home>
glab.versionWhich GitLab CLI release to install. It is a release asset rather than a distribution package because no distribution carries glab.1.111.0
hostinger.zonesDNS zones this provider may manage. Set this when the token has DNS permission without Domains portfolio permission; an empty list asks the account portfolio instead.[]
kimi-code.homeWhere the account’s home is.<the account's own home>
mac-brew.casksHomebrew casks to install.[]
mac-brew.formulaeHomebrew formulae to install.[]
mac-brew.prefixWhere Homebrew lives. Left unset, /opt/homebrew on Apple Silicon and /usr/local on an Intel Mac./opt/homebrew
mac-brew.tapsHomebrew taps to add.[]
mac-brew.trusted_casksCasks to trust, as full names <tap>/<cask>. Recent Homebrew refuses to load a cask from an unofficial tap until it is trusted, per item on purpose rather than per tap.[]
mac-brew.trusted_formulaeFormulae to trust, as full names <tap>/<formula>, for the same reason as trusted_casks.[]
mac-mise.binWhere the mise binary is.~/.local/bin/mise
mac-mise.toolsTools to install globally, as mise use -g takes them, e.g. node@lts.[]
mac-ports.portsMacPorts ports to install, e.g. git or ripgrep.[]
mise.homeWhere the account’s home is.<the account's own home>
opencode.homeWhere the account’s home is.<the account's own home>
pi.homeWhere the account’s home is.<the account's own home>
scheduled.homeWhere the account’s home is.<the account's own home>
scheduled.versionThe devmachine release the workspace runs its tasks with. Empty means the release of the CLI that syncs, so both sides speak the same version; a CLI built from source falls back to 0.14.0.(empty)
sentry.homeWhere the account’s home is.<the account's own home>
session-share.homeWhere the account’s home is.<the account's own home>
session-share.portThe local port this account’s share server listens on. Every workspace on a machine needs its own.7690
session-share.versionThe session-share release to install. A sync replaces an installed binary of another version.0.1.7
ssh_hardening.serviceWhat systemd calls sshd. Empty means the name this distribution family uses, which is ssh on Debian and Ubuntu and sshd elsewhere. macOS ignores it: launchd starts sshd for each connection, so there is nothing to reload.(empty)
tailscale.exit_nodeAdvertise this machine as an exit node. Off unless asked for.false
tailscale.login_serverThe control server devmachine login tailscale joins. Empty means Tailscale’s own; a URL means your own, such as Headscale.(empty)
workspace.admin_homeThe home of the account the CLI provisions with. Whatever reaches that account over SSH is what reaches this workspace. It is read from the system: root’s home, or the admin login’s own when that is not root.<the admin login's own home>
workspace.git_emailThe address on this workspace’s commits.(empty)
workspace.git_nameThe name on this workspace’s commits.(empty)
workspace.groupsExtra groups the account joins. The docker group is one of them and it is effectively root, so nobody joins it by accident.[]
workspace.homeWhere the account’s home is. It is read from the account; a new account gets /home/ unless this says otherwise. On macOS a new account always gets /Users/.<the account's own home>
workspace.known_hostsThe hosts whose SSH host key is trusted in advance, so the first clone does not stop to ask a question nobody is there to answer.[github.com]
workspace.reposRepositories cloned into ~/dev/, once. A clone is never pulled, reset or removed afterwards, and a folder already at ~/dev/ is left as it is. A clone over SSH waits for the workspace’s key, which a package such as git-key delivers after this one runs, so it happens on the second pass of the same sync. Each entry: branch: The branch checked out on the clone. Left out, the remote’s default; name (required): The folder under ~/dev. Letters, digits, dot, dash and underscore; url (required): Where it is cloned from, over SSH or HTTPS.[]
workspace.shellThe login shell. Empty means the system’s default for a new account (useradd’s on Linux, /bin/bash on macOS), and the package that installs a shell is the one that sets it.(empty)
workspace.sign_commitsSign every commit and rebase, once a package such as git-key sets up a key.true
zsh.homeWhere the account’s home is.<the account's own home>
zsh.tmux_auto_attachOpen a tmux session on every SSH login, so a dropped connection loses nothing. A second connection while the first is live gets a session of its own instead of a second view of the same one.true
zsh.tmux_configWrite the account’s ~/.tmux.conf. Turn it off to keep a config of your own.true