Setup

New VM Setup

This page covers two things: the operator steps to provision a VM and hand it off, and the user setup wizard the user completes themselves after receiving their URL.

Part 1: Operator setup

These steps take about 5 minutes. You need the hub VM URLs from the Deployment step and your TOTP app.

1. Provision a VM

Create a new VM at exe.dev (or any Linux host with Docker). A 4GB RAM instance is comfortable for one or two projects. The VM should have a public hostname — exe.dev assigns one automatically.

2. Run setup

git clone https://github.com/butaud/claude-harness.git
cd claude-harness
sudo bash session-manager/scripts/setup.sh

The script will prompt for:

PromptWhat to enter
Publish server URL The hub's publish server address, e.g. https://hub.example.com:3002
Authenticator code 6-digit TOTP code from your authenticator app (the one you scanned from the publish server)
Messaging router URL The hub's router address, e.g. https://hub.example.com:3923

The script then builds Docker images, starts the harness, and creates a starter my-app project. This takes 3–5 minutes.

3. Send the user their URL

When the script finishes it prints the dashboard URL — something like https://chimera-sweet.exe.dev. Send that to the user. Nothing else is needed from you.

✓
The VM is ready the moment the script exits. The user can open it immediately and start the wizard.

Part 2: User setup wizard

The user opens their URL and sees the setup wizard. This covers the four steps they'll complete on their own.

Step 1 — Scan the QR code

The first thing shown is a QR code. The user scans it with their authenticator app (Google Authenticator, Authy, 1Password, etc.) and enters the 6-digit code to confirm. This code is how they'll log into the dashboard — write it down or save it in your password manager.

ℹ
This TOTP secret is for the harness UI only, separate from the operator's publish-server TOTP. Each VM generates its own.

Step 2 — Choose your account name

Enter a short name for yourself — something like alice or myname. This becomes the prefix for all your published project URLs: yourname-project-id.pages.dev. You can change it later by going through setup again.

Step 3 — Connect Claude

The wizard shows a Connect Claude button. Clicking it:

  1. Starts Claude Code in the container The harness runs Claude Code with its stdin/stdout piped. Claude prints an Anthropic sign-in URL.
  2. Shows you the sign-in link The page displays an Open Anthropic sign-in button. Click it — it opens the Anthropic auth page in a new tab.
  3. Paste your token After signing in, Anthropic shows a token. Copy it and paste it into the input on the wizard page, then click Submit.
  4. Done The harness sends the token to the waiting Claude Code process. Claude saves its credentials and the wizard advances.

No terminal needed. The token goes directly from your browser to your container.

Step 4 — Connect Discord

The wizard shows a pairing code like PINE-7342 and a link to open a DM with the bot.

  1. Add the bot to a server If you haven't already, click Add bot to Discord. Select any server you manage (a personal server works fine) and click Authorize. Discord requires bots to share a server before they can DM users.
  2. Open a DM with the bot Click Message the bot. This opens the bot's Discord profile where you can start a DM.
  3. Send the pairing code DM the bot your code exactly as shown (e.g. PINE-7342). The wizard detects the pairing within a few seconds and advances.

Setup complete

The wizard disappears and the normal dashboard appears. Claude sends you a greeting on Discord letting you know it's online and the starter project is ready. You're set up.

✓
The whole user wizard takes about 5 minutes. No operator involvement needed once the VM URL is shared.