devmachine

Concepts

Packages

A package adds something to your server or to a workspace: Claude Code, Docker, your GitHub login.

Add one with devmachine packages add <name>, then run devmachine sync to install it. devmachine packages list shows what exists. The published packages live at github.com/mydevmachine/packages, and you can write your own.

Which packages exist

devmachine packages list

lists every package your configuration can use, with a short description of what each one does. devmachine packages help <name> prints what a package accepts, straight from the package itself.

Server packages and workspace packages

A server package installs once and serves everyone on the machine — Docker, the firewall, Caddy. A workspace package belongs to one person — Claude Code, zsh, a dotfiles setup — and can go on as many workspaces as you want.

devmachine packages add docker --machine main
devmachine packages add claude-code --workspace acme

Adding the wrong kind to the wrong target is refused, and says why.

The essentials

setup gives a new server one package, essentials, which installs nothing itself and pulls in others: base, git, firewall, ssh_hardening, caddy and devmachine-app. --no-essentials starts the server bare. A Mac starts with base, devmachine-app and its package manager package instead, since essentials runs only on Linux. See what a new machine starts with.

Changing a package’s settings

A package reads its own settings, each with a default. Change one on a workspace with:

devmachine workspaces edit acme --set [email protected]

An empty value, --set caddy.email=, removes the override. On a machine, edit settings: directly in config.yml — see Configuration.

What a package is made of

A package is a folder: an Ansible role, the part that installs things, plus one file, package.yml, that tells devmachine what the package is. The folder’s name is the package’s name.

sharing/
  package.yml          what the package is
  tasks/main.yml       what it installs
  defaults/main.yml    the default value of each setting
  files/               anything it copies to the machine

This is a complete package.yml, using the fields most packages need:

format: 1                  # the shape of this file
name: sharing              # same as the folder
scope: machine             # machine or workspace
summary: File sharing, uploads by API key and downloads by public link.
category: Web              # groups it on the packages page
requires:
  cli: ">= 0.7.0"          # the oldest CLI that can run it
needs: [docker, caddy]     # installed before this one
extends:
  caddy.sites.d: files/sharing.caddy   # a site file handed to Caddy
variables:
  port:
    summary: The port the container listens on.
    default: 53842
credentials:
  - name: sharing_api_key  # something only you can give it
    kind: secret
    scope: machine
    env: SHARING_API_KEY

Only the first four fields are required. The official schema, straight from the CLI:

FieldRequiredWhat it is
formatyesThe shape of this file. This CLI reads format 1.
nameyesThe package’s name, which has to be the directory it lives in.
scopeyesWhere it is installed: “machine” or “workspace”.
summaryyesOne line saying what it installs. It is what packages list prints.
categoryA word or two grouping it with packages like it, such as “Security” or “DNS”. The packages page filters by it.
platformsThe operating systems it runs on: “linux”, “macos”, or both. Left out, any.
requiresWhich CLI can run it, written as requires.cli: ”>= 0.2.0”.
needsPackages that have to run before this one. It is the only thing that decides order.
providesPlaces other packages may write into, as : .
extendsContributions to another package’s place, as .: .
variablesValues this package reads, each with a summary and a default.
credentialsWhat its tool cannot work without, and how each one is obtained.
requires_filesFiles that have to be on the machine before it runs.
skillsA package-relative directory whose direct children are Agent Skills.
kindThe contract an entrypoint answers. The only one so far is “dns”.
entrypointAn executable in the package the CLI can call on the machine.
commandsWhat the entrypoint accepts: a list, or [”*”] for anything.

The CLI is the source of truth for this list: devmachine packages schema --json prints it, and devmachine packages validate <folder> checks a package against it, reporting every problem at once. Each field is explained in full, with its rules, in the package format.

Writing your own

<config>/packages/ holds packages you write yourself, in the same format as the published ones, and a package there with the same name replaces an official one.

Start one with devmachine packages new <name>: it writes a package that already passes packages validate. Browse the official ones on the packages page for examples, and read why packages work this way for the reasoning behind it.

Packages from other people

devmachine packages install https://example.com/alice/tools.git brings in a package somebody published in a git repository. It shows what the package brings and asks first. It lands in <config>/packages/ beside your own, with a .devmachine-source.yml saying where it came from; packages update <name> fetches it again and packages remove <name> deletes it. Its widgets that run code ask before they run. See where a public widget comes from.