skiff – a fresh Linux VM on your Mac in half a second

skiff gives you throwaway Linux VMs on Apple Silicon, one per task or coding
agent: skiff new dev boots an Ubuntu 24.04 VM with its own kernel, disk, IP
and root SSH in about two seconds (the boot itself takes half a second), and
skiff rm dev throws it away. Credentials the agent needs stay on the Mac and
reach the VM through a broker, never as copies.

macOS (skiff)
 ├── VM dev   (Virtualization.framework via Apple's `container`, 192.168.64.x, ssh dev.skiff)
 ├── VM ai    (…)                                     ──┐ relay: localhost:3000 → ai:3000
 └── broker   (credentials, MCP servers, audit log)   ◀─┘ ssh -R tunnel per session

Each VM is a container machine: a Virtualization.framework VM driven by
Apple's container CLI. There is no
nested virtualization and no shared runtime VM, so JIT-heavy workloads such as
Claude Code run at Mac speed. The host side is one Go binary; the guest is a
plain Ubuntu image with systemd, sshd and skiff's key.

Requirements

• Apple Silicon (any generation)
• macOS 26 or newer (what Apple's container supports)
• Homebrew (skiff installs container through it if needed)
• Go 1.26+ to build skiff

Check with skiff doctor.

Install

go install github.com/sovyn-eu/skiff/cmd/skiff@latest
skiff prepare           # one-time setup, about a minute

Or from a checkout: make install (go install ./cmd/skiff → $(go env GOPATH)/bin/skiff).

skiff prepare is idempotent. It:

1. verifies the host (Apple Silicon, macOS version, Hypervisor framework, container),
2. generates an SSH key pair in ~/.skiff/,
3. starts the container system service (first run downloads Apple's guest kernel),
4. builds the guest image skiff/guest (Ubuntu 24.04 with systemd, sshd,
   your public key and the internet-only firewall), rebuilt only when the
   image recipe or your key changes,
5. writes ~/.skiff/ssh_config.

Why Apple's container

skiff started as Firecracker microVMs inside a Lima VM with nested
virtualization. Measured on an M4 Pro (2 vCPU / 1 GiB guests), the nesting
cost JIT-heavy workloads such as Claude Code about twice the CPU, which is why
skiff moved to one Virtualization.framework VM per guest:

There are no golden snapshots (every boot is cold and fast), no image
profiles (install what a task needs over ssh) and no --disk (the root disk
is a sparse 512 GiB volume that grows on demand); VMs need at least 1 GiB of
memory.

Usage

skiff new                    # boots vm1 (2 vCPUs, 1 GiB RAM, 2G disk)
skiff new dev --vcpus 4 --mem 2048
skiff ls
skiff ls --json              # also: new --json, inspect --json
skiff inspect dev            # details of one VM
skiff ssh dev                # interactive root shell
skiff ssh dev uname -a       # run a command (a shell command line, like plain ssh)
skiff exec dev -- git commit -m "it's done"   # exact argv, every word quoted
skiff stop dev               # keep the disk
skiff start dev
skiff rm dev                 # stop and delete
skiff gc --owner paseo       # remove VMs a tool created and lost track of

Owned VMs and skiff gc

Tools that create VMs on your behalf label them with an owner and, if they keep a
pool, a slot. skiff records both together with the creation time in the VM's
directory, so the labels disappear with the VM:

skiff new paseo-3 --owner paseo --slot 3
skiff ls                             # OWNER shows paseo/3, AGE the time since creation
skiff gc --owner paseo --keep paseo-1 --keep paseo-2   # a tool reconciling its pool
skiff gc --older-than 7d --dry-run   # owned VMs older than a week

gc only ever removes VMs that have an owner; VMs created by hand have none and
are never collected. --owner and --older-than select which owned VMs go,
--keep exempts VMs by name, and --dry-run shows the plan. Without --owner
or --older-than, gc removes no VM and only deletes the grants and tokens left
on the Mac for VMs that no longer exist. A VM a tool is creating right now is not
in its keep list yet; guard it with --keep or --older-than. gc --json
reports {"vms": [...], "host_state": [...], "dry_run": ...}.

Port forwarding

skiff new web -p 8080:80 -p 3000    # forwards at creation
skiff forward web 5432              # localhost:5432 -> web:5432
skiff forward web                   # list
skiff unforward web 5432

Forwards appear as localhost:PORT on the Mac, persist across stop/start
and a reboot, follow the VM to a new address, and are removed with the VM. Host
ports must be 1024 or higher because the relay runs as your user. Under the
hood skiff _relay, started by skiff whenever forwards exist, listens on the
host port and joins each connection to the VM's guest port; a stopped VM keeps
its port and connections are closed until it runs again. skiff forward web
shows each forward as active or inactive.

To use plain ssh, add one line to ~/.ssh/config:

Include ~/.skiff/ssh_config

Then ssh dev.skiff works from anywhere, including scp, rsync and your IDE.
The alias runs skiff _dial as ProxyCommand, which connects to the VM's
current address and verifies the host key pinned at creation, so no port
forwarding or sudo is needed on macOS.

Capabilities: credentials and MCPs without copying secrets

A VM is isolated from your Mac on purpose. When an agent inside needs
GitHub, Claude Code or an MCP server that only runs on the Mac, skiff opens
one controlled hole: a broker that hands out connections, never secrets.

skiff secret set claude-token          # paste the output of `claude setup-token`
skiff secret set github-token          # a fine-grained token, limited to the repos the agent may use
skiff grant agent1 claude github ssh-agent
skiff ssh agent1                       # the broker lives as long as this session
skiff grants agent1
skiff revoke agent1 github

While skiff ssh is open, the broker listens on a Unix socket on the Mac and
ssh forwards it to 127.0.0.1:7777 inside the guest (-R). Tools in the guest
talk to that address with a per-VM placeholder token; the broker swaps it for
the real credential from the macOS Keychain. The socket identifies the VM, so
there is nothing in the guest worth stealing, and the hole closes with the
terminal. ssh-agent is a built-in grant that adds -A; pair it with
ssh-add -c to confirm every signature. For clients that only speak HTTP over
a Unix socket, the guest also gets /run/skiff/broker.sock while any
capability is granted: a systemd socket that relays to the same tunnel.

When something other than skiff ssh drives the guest, such as an editor or
an agent runner with its own ssh session, keep the broker up with
skiff tunnel agent1. It holds only the forward, reconnects when the
connection drops, logs tunnel=open|closed to the audit log and ends with
Ctrl-C or when the VM stops. skiff ssh agent1 keeps working alongside it
and uses the running broker instead of forwarding a second time; if the session
or tunnel that owns the broker ends first, the remaining session takes it over
within a few seconds.

Grants are the only policy: default deny, one file per VM in ~/.skiff/vms/,
checked on every request and logged to ~/.skiff/audit.log. A denied request
answers with the exact skiff grant command that would allow it. A grant is
all or nothing per capability: what a granted VM can reach is what the
credential behind it can reach. Limit that at the source, for GitHub with a
fine-grained token restricted to the repositories the agent works on. GitHub
enforces that limit itself, and the token never enters the guest.

The broker is harness-neutral. It knows three primitives, and everything
specific to Claude Code, GitHub or any other tool is a capability file:

skiff cap ls                           # embedded: claude, github; yours in ~/.skiff/caps
skiff cap show claude                  # the TOML file
skiff cap show github --render --vm agent1   # what the guest receives
skiff cap init codex                   # commented skeleton, then: skiff cap lint codex
skiff cap add https://example.com/gemini.toml   # shown before it is installed

A capability declares the primitive plus a [guest] section with environment
variables, files, managed blocks inside shared files (such as /etc/gitconfig)
and JSON merges, all templated with .BrokerURL, .BrokerSocket, .PseudoToken
and .VM. Secrets (keychain:, env:, cmd:, file:) are only valid on the
broker side; skiff cap lint rejects them in guest sections. Header
templates can encode Basic credentials with
{{ secret "ref" | basicauth "user" }}. A proxy can add [[proxy.routes]]:
requests that reach the broker for another host (for example through
.BrokerSocket) go to that route's upstream with its own headers. A user file in
~/.skiff/caps/<name>.toml replaces an embedded capability of the same name.
See examples/caps/ for an MCP bridge and an exec plugin.

The embedded github capability serves git and the gh CLI with one token.
git is rewritten to the broker in /etc/gitconfig; gh sends its API calls
through .BrokerSocket (http_unix_socket) with a placeholder token in its
hosts.yml, which gh reads on every call, so a grant applies to running
processes without a restart. Paths with percent-encoding are refused, and
downloads that GitHub redirects to other hosts (gh release download) do not
work through the broker. Route hosts must be public DNS names, never an IP or
localhost, so no capability can catch the requests of another.

The embedded claude capability points ANTHROPIC_BASE_URL at the broker and
sets CLAUDE_CODE_OAUTH_TOKEN to the placeholder, so the unmodified Claude Code
binary in the guest sends exactly the headers of a normal subscription login.
Usage draws on your own subscription like any other session. Anthropic's terms
allow signing in to the unmodified binary with your own subscription, including
in sandboxes you run; they do not allow routing other people's requests through
your account, so keep the broker personal.

How a VM is wired

Network isolation

The guest image carries an nftables ruleset that rejects connections from the
VM to private networks: the Mac at 192.168.64.1, your LAN, other VMs, and
link-local and carrier-grade ranges. DNS and DHCP to the gateway stay open, the
internet is reachable through vmnet's NAT. It is a guard rail inside the guest,
not a boundary: root in the VM can lift it. The only controlled way back to the
Mac is the capability broker.

Because all VMs share one vmnet subnet, skiff new reads each VM's ssh host
key right after its first boot and pins it; a VM that takes a neighbour's
address cannot pose as it towards skiff ssh, grants or the broker tunnel.

Troubleshooting

• skiff doctor explains what is missing on the host.
• Boot log of a VM: container machine logs NAME
• Port forwards: skiff forward NAME shows their state; the relay logs to ~/.skiff/relay.log.
  The relay runs as a child of your terminal (macOS denies a launchd agent the local
  network), so it ends at logout; the next skiff command starts it again.
• After a reboot of the Mac, the next skiff command starts the container service and
  the VMs that were running come back. VMs stopped with skiff stop stay stopped.
• ssh reports Host key verification failed for a VM created before host keys were
  pinned, or one replaced under the same name: recreate it.
• skiff ssh and skiff exec mirror the remote exit status; exit 255 means the connection failed.
• skiff ssh dev a b joins its words into one shell command line, as ssh does, so
  quotes and $ are interpreted by the guest shell. Use skiff exec dev -- a b from
  scripts: it quotes every argument and the guest sees exactly that argv.
• Ctrl-C during skiff new NAME removes the half-created VM again.
• Reset everything: skiff rm each VM, then rm -rf ~/.skiff and
  container image rm skiff/guest:latest.

Development

make test     # unit tests (with -race)
make cover    # coverage summary
make lint     # gofmt, go vet
make e2e      # boots a real VM (requires skiff prepare), cleans up afterwards

Layout: cmd/skiff (entry point), internal/cli (cobra commands),
internal/app (workflows), internal/backend (the interface, the container
backend and an in-memory fake for tests), internal/host (host facts),
internal/broker (per-VM capability broker), internal/cap (capability files,
embedded defaults), internal/grant (per-VM policy), internal/guest
(guest provisioning scripts), internal/secret (Keychain/env/cmd/file resolver),
internal/vm (spec validation), internal/sshcfg (ssh_config rendering).

Contributing

Bug reports and pull requests are welcome. Please read
CONTRIBUTING.md for the development setup, coding
guidelines and PR process, and SECURITY.md for how to report
vulnerabilities privately. This project follows the
Contributor Covenant.

License

skiff is licensed under the Apache License 2.0.
Copyright 2026 IT-Labs GmbH. Apple's container CLI, its guest kernel and the
Ubuntu image are installed or downloaded at skiff prepare time and keep
their own licenses; see NOTICE.