Quick start

From nothing to your first agent.

Nine steps, about as long as a cup of coffee for the first box. No files to edit, no infrastructure to learn. jauntbox is in beta: you build it from source.

1. 1

   Prerequisites

   • Go, to build the binary.
   • A dedicated Hetzner Cloud project and an API token for it (HCLOUD_TOKEN). Never point jauntbox at a project that holds other resources.
   • A Tailscale API key (TAILSCALE_API_KEY).
   • A GitHub organisation or personal account to own the private GitHub App, and gh logged in on your laptop (or GITHUB_ADMIN_TOKEN set) for the one-off App setup.
   • A Claude Code credential for the agents: run claude setup-token on your laptop and keep the token for step 5.
2. 2

   Build from source

   During the beta there are no packaged installs.

   $ git clone https://github.com/WA-Systems-EU/jaunt && cd jaunt
   $ go build -o ~/bin/jauntbox ./cmd/jauntbox

3. 3

   Initialise

   jauntbox init detects your user, SSH key and timezone, asks for the two API tokens and checks both, picks server types, and writes ~/.config/jauntbox/config.yaml (never the tokens). It can save the tokens to ~/.config/jauntbox/env (mode 0600), which jauntbox reads when the variables are unset; or it prints two export lines for your shell profile.

   $ jauntbox init

   Prefer editing by hand? Copy examples/jauntbox.yaml to ~/.config/jauntbox/config.yaml. See the configuration reference.

4. 4

   Allow the box in your tailnet policy

   Init prints the Tailscale policy snippet. Paste it into the access controls of your tailnet. It also lets you ssh to the box as root, which jauntbox uses for its own privileged steps. Reprint it any time:

   $ jauntbox acl-snippet

   If root ssh is not allowed, commands that reach the box fail with root ssh to <host> failed. Paste the current snippet and retry.

5. 5

   Set up GitHub and secrets

   Create the private GitHub App (it opens your browser and asks which account owns it), then install it on the repos you want agents to touch. Why a private App and not a token or a deploy key? Nothing long-lived lands on the box, and each agent run gets a one-hour token for its own repo only. Why a private GitHub App.

   $ jauntbox setup github

   Store the agent credential and the box sudo password. Both are prompted for and never echoed; secrets stay on the laptop in ~/.config/jauntbox/secrets/ and are pushed into the box's memory.

   $ jauntbox secrets set CLAUDE_CODE_OAUTH_TOKEN  # paste the token from claude setup-token
   $ jauntbox secrets set BOX_SUDO_PASSWORD        # the password for sudo on the box (not empty)
   $ jauntbox secrets list                         # names only, never values

   On GitHub Free, rulesets are not available on private repos; setup github names the repos it cannot protect. See GitHub and rulesets.

6. 6

   Start a box

   up returns at once; the box is ready a few minutes later. Add --wait to block until it is.

   $ jauntbox up small
   $ jauntbox status      # box, tailnet presence, deadline and verdict

7. 7

   Attach and unlock

   Bare jauntbox brings the box up if needed, waits, and attaches your persistent herdr session. It reconnects after network drops.

   $ jauntbox

   Laptop commands that reach the box unlock it automatically. Run an explicit jauntbox unlock after you change a secret or if jauntbox status shows the box as locked.

   $ jauntbox unlock

   A new or rebooted box starts locked: its secrets live only in its RAM, never on its disk, so nothing is left to find on a rebooted or snapshotted server. What locked means.

8. 8

   Clone a repo and start your first agent

   On the box, git needs your identity (agents commit as you). Then clone a repo under ~/src. jaunt-repos lists the repos the GitHub App is installed on and clones them.

   $ git config --global user.name "Your Name"
   $ git config --global user.email you@example.com
   $ jaunt-repos
   $ cd ~/src/<repo>
   $ jauntctl agent

   The first run builds the agent image, which takes minutes (it says so first). Claude then opens right there in the pane, in a container, with only this checkout and a token for this one repo. To watch an agent that works on its own: jauntctl agent --unattended "one-line prompt" and jauntctl agent logs --follow.

   More on agents and what they cannot reach.

9. 9

   Finish the day

   jauntbox down wraps up the agents, revokes tokens and deletes the box. The volume with your code stays. Forget it and the box deletes itself at 19:00, after 10 hours, or when idle.

   $ jauntbox down

   Tomorrow, jauntbox builds a fresh box on the same /home.