Link this box to your v-code.dev account

Agents: claude, codex, opencode, cursor · On: desktop · beta

Link the machine VCode runs on (the box) to your v-code.dev account with your email and an emailed code. A linked box connects out to the VCode router, and any device signed in to that account can reach it from app.v-code.dev.

Why you would use it

You want VCode on your phone without a Tailscale tailnet or a Cloudflare tunnel of your own. The box makes an outgoing connection only, so nothing on your network has to accept one. Linking is the only step: then sign in on the phone (add-a-phone).

How to use it

To set up a new box, start from "Add a computer" on app.v-code.dev instead (add-a-computer). Its command installs the box, links it and pairs the browser that showed it, in one step, with no email or code to type. On a box already installed, the same command links it (or keeps the link it has to the same account) and pairs the browser, and restarts nothing. From a terminal, that step is v-code box join, which reads the join code on stdin.

From a terminal on the box:

v-code box link      # asks "Email: ", then "Code sent to <email>: "; prints "Linked as <email>"
v-code box status    # Box, Linked, State, Box fingerprint, Paired devices
v-code box unlink    # prints "Unlinked; paired devices removed"

v-code box reads VCODE_PORT and AUTH_TOKEN from ~/.config/v-code/env (or the file VCODE_ENV_FILE names). On a box the rename has not moved yet, it reads ~/.config/claude-portal/env instead. Inside a VCode thread it uses the thread's VCODE_API and VCODE_TOKEN, unless VCODE_ENV_FILE is set. A file it cannot read stops it with exit code 2, naming the path: "run it inside a thread, or set VCODE_ENV_FILE", or, when VCODE_ENV_FILE named it, "the file VCODE_ENV_FILE names; fix or unset it".

What you see

v-code box status prints State: as one of:

State	Meaning
`local`	Not linked.
`connecting`	Linked, opening the socket to the router.
`online`	Connected to the router. Devices signed in to the account can reach the box.
`offline`	Linked, no socket right now. It reconnects on its own.
`revoked`	The box was removed on your account page. Link it again.
`replaced`	Another process holds this box's key on the router. Stop the other process, then restart VCode.

A refused link prints the site's own message. An account without premium gets "This account needs premium to link a box." and the box stays local. A wrong code, a bad email or too many tries keep the site's wording. A code that is not eight digits never reaches the site: the box answers "code must be eight digits".

On a server without AUTH_TOKEN every v-code box command fails with "linking or pairing this box needs AUTH_TOKEN set on the server".

Unlinking keeps the box on your account. The box cannot remove itself from the account; remove it on your account page.

Options and settings

Option	Default	What it changes
`VCODE_BOX_DIR`	`<dirname of VCODE_STATE>/box`	Where the box key, its link to your account and its list of paired devices live. Made 0700; a looser directory or another owner fails the boot.
`VCODE_SITE_URL`	`https://v-code.dev`	The login site the box links through.
`VCODE_ROUTER_URL`	`wss://router.v-code.dev/box`	The router a linked box connects to.
`VCODE_NAME`	machine hostname	The box name your account's box list shows.

Limits and known gaps

Linking, unlinking and pairing need AUTH_TOKEN on the server; without it any local user could link the box.
A paired phone cannot link, unlink or pair.
Unlinking forgets the account link and the paired devices but keeps the box key, so a relink is the same box on your account. It does not remove the box from the account; do that on the account page.
The settings sheet has no remote access group. Link from a terminal, or with Add a computer.