Setting Up Devbox

Setting up a PostHog devbox

A devbox is a Coder workspace on EC2 for PostHog development. Drive it through hogli devbox:* and don't reimplement what those commands do. A new box has the repo at ~/posthog on master, prewarmed dependencies, and Claude Code installed. hogli devbox:<command> --help has the current flags. This skill covers the order of operations and what the help text leaves out.

People use a box in different ways: a shell or editor for general development, a remote target for a local checkout, or a host for the running PostHog app. Work out which one the user wants, and don't start the PostHog stack unless they ask for the app.

Get a box

Copy this checklist and track it:

- [ ] 1. hogli devbox:doctor: the tailnet and control plane checks are ok
- [ ] 2. hogli devbox:setup has run on this machine
- [ ] 3. hogli devbox:start: the box is running
- [ ] 4. The user is connected the way they asked for
- [ ] 5. hogli devbox:stop when the user is done

1. Check access

hogli devbox:doctor is read-only: it never prompts or changes host config. Commands that reach a box run the same reachability check first, so fix a failure here before anything else.

• The active tailnet must be posthog.com. Doctor prints it and names a wrong tailnet as the cause.
• Every PostHog employee has the route to the Coder control plane through group:employees in the tailnet policy. Nobody needs a PR to get access.
• If doctor reports the control plane unreachable, read references/access-troubleshooting.md before changing anything.
• [missing] Commit signing agent does not block starting or using a box. It matters only for signed commits made on the box.

2. Set up this machine once

hogli devbox:setup is interactive, so ask the user to run it in their own terminal. It installs the Coder CLI at the server's version into ~/.hogli/bin, logs in, installs the pinned mutagen binary for devbox:sync, and writes the coder.* SSH host entries that devbox:ssh and devbox:exec use. ~/.hogli/bin is not on PATH, so call that CLI as ~/.hogli/bin/coder when a step needs coder directly. Each optional step has a --configure-<step> and --skip-configure-<step> flag: ssh, git-identity, git-signing, region, dotfiles, claude. Run it again when a command prints Coder CLI vX does not match server vY, because it reinstalls the matching CLI.

On Linux, the reachability check can run sudo tailscale set --accept-routes and prompt for a password. Run setup interactively once before an agent drives devbox commands unattended.

3. Start the box

hogli devbox:start

This creates the box on first use and resumes it after a stop. It brings up the PostHog stack only when the workspace has --start-app set, which is covered in Run the PostHog app. --disk (100 or 200 GiB) applies only when the box is created. --region (us-east-1 or eu-central-1) starts that region's default box and creates it if it doesn't exist, so leave it off when resuming an existing box. A box's region can't change.

The default box is devbox-<coder-user>, and a labeled box is devbox-<coder-user>-<label>. Boxes in eu-central-1 add an -eu suffix, for example devbox-<coder-user>-eu. hogli devbox:list shows the exact names. Target a labeled box with -n <label> on commands that act on a box.

4. Connect

Match what the user asked for:

• Shell: hogli devbox:ssh.
• Editor: hogli devbox:open --vscode, --cursor, or --web.
• Commands from an agent: hogli devbox:exec, described in Run commands on the box.
• Edit locally, run on the box: read references/sync.md before using hogli devbox:sync.
• The running app: follow Run the PostHog app.

5. Stop when done

hogli devbox:stop keeps the disk and stops billing. Stops, starts, and devbox:update keep /home. hogli devbox:destroy deletes it, so don't keep anything irreplaceable only on a box.

Run commands on the box

hogli devbox:exec -- <command> runs one command over SSH and returns its exit code. Wrap the command in bash -lc '...'. A non-login shell doesn't reliably load the shell profile, so tools on a login-shell PATH such as ~/.local/bin report "command not found". Put -- between hogli's flags and the command's own. devbox:exec and devbox:ssh fail to connect until devbox:setup has written the SSH config.

Run the PostHog app

Use this section only when the user wants the app, for example to QA a change or share a link.

Start the stack

• New or stopped box: hogli devbox:start --start-app. The flag stays set on the workspace, so every later start brings the stack up in the background until hogli devbox:start --no-start-app turns it off. Either flag takes effect only when the box is created or starts from stopped; on a running box hogli skips it and prints a note.
• Running box: hogli devbox:exec -- bash -lc 'cd ~/posthog && ./bin/hogli up -d -y'.

Wait for it

The stack keeps booting after the start command returns. Poll in a bounded loop until this prints 200 or 302. A 000 or 502 means the stack is still booting.

hogli devbox:exec -- bash -lc "curl -s -o /dev/null -w '%{http_code}' --max-time 10 http://127.0.0.1:8010/"

When resuming QA on an existing box, check it before recreating sync, restarting the stack, or making a new box:

hogli devbox:status
hogli devbox:exec -- bash -lc 'cd ~/posthog && git status --short --branch && git rev-parse --short HEAD'
hogli devbox:sync --json

Keep going when the app serves the intended branch and SHA, the target route loads, and its APIs work. Note unrelated degraded processes instead of chasing full health.