Boxes

A Box is a persistent Linux virtual machine in your Lane that you reach over SSH. Use one for development, long-running jobs, or as a home for your coding agent.

Create a Box

af box create agent1 --size S --json

{
  "ok": true,
  "data": {
    "created": true,
    "machine": {
      "name": "agent1",
      "kind": "box",
      "size": "S",
      "state": "running",
      "ip": "…",
      "ssh": "ssh you@…",
      "hostKeyFingerprint": "SHA256:…",
      "vcpu": 4,
      "memoryGiB": 8,
      "diskGiB": 50,
      "createdAt": "2026-11-02T09:14:03Z"
    }
  }
}

• Names are lower-case letters, digits and dashes, starting with a letter, 2 to 31 characters.
• create waits until SSH answers, for up to 300 seconds (--timeout to change it). --no-wait returns as soon as the machine exists, with state: starting. If SSH has not answered by the timeout, create still succeeds with a warning; check later with af box show agent1 --json.
• Creating a name that already exists, with the same size, returns it with "created": false. That makes create safe to retry.
• Your Lane needs at least one SSH key first (SSH keys). Without one, create stops with NO_KEYS rather than make a Box nobody can enter.

Connect

af box ssh agent1                  # opens SSH
af box ssh agent1 --json           # prints the ssh command instead
af box ssh-config agent1           # a ready ~/.ssh/config entry with the host key pinned

Your user on the Box is your Lane’s name. af pins each Box’s host key in ~/.config/af/known_hosts; check hostKeyFingerprint before you trust a host. Password login is off: only your Lane’s SSH keys get in.

With the ssh-config entry in ~/.ssh/config, editors such as VS Code Remote-SSH and Cursor connect by the Box’s name.

Resize

af box resize agent1 --size M --json

• CPU and RAM grow or shrink; disk only grows. A smaller size keeps the larger disk, which diskGiB shows.
• Because a Box’s cores are its own, a resize usually needs a restart. You get RESTART_REQUIRED; repeat with --restart when you are ready.

Stop and start

af box stop agent1 --json
af box start agent1 --json

A stopped Box keeps its disk and frees the platform’s CPU and RAM. It still counts against your Lane’s caps.

Delete

af box delete agent1 --confirm agent1 --json

This deletes the Box and all its snapshots, and cannot be undone. Without --json it asks you to type the name instead.

Check on your Boxes

af list --kind box --json
af box show agent1 --json          # also lists the SSH keys a running Box accepts

Before something risky, take a snapshot: Snapshots and restore.