Link this box to your fezu.dev account

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

Link the machine VCode runs on (the box) to your fezu.dev account: VCode opens on its login card, you log in or create an account with your email, and the box is linked to that account. A linked box connects out to the VCode router, and any device signed in to that account can reach it from app.fezu.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 workstation on fezu.dev/account instead (add-a-workstation). Its command installs the box and links 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 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      # opens VCode on its login card; prints "Linked to <email>"
v-code box app       # opens the VCode desktop app signed in to the box's account; links first when the box is not linked
v-code box status    # Box, Linked, State, Box fingerprint, Paired devices
v-code box unlink    # prints "Unlinked; paired devices removed"

1. Run v-code box link. It opens VCode: the desktop app when it is installed, else Chrome (Chromium on Linux, Edge on Windows, Safari on a Mac), else your default browser. The terminal prints:

   Opening VCode to connect this computer…
   If it doesn't open, go to https://fezu.dev/link?state=<state>&name=<box name> on any device, and paste the code it shows here:
   

   Copy

2. VCode shows its login card (#rs-login), which reads Create an account or log in to connect <box name>. We send a code to your email. Cancel (#rs-login-cancel) drops the link and shows the plain login card. Type your email in #rs-login-email and click Continue (#rs-login-go).

3. fezu.dev's link page sends a code to that email. Enter it. A new email makes a new account, with 30 days of the full plan (free-trial); an email you have used logs in to your account. The steps are the same.

4. The site links the box to that account and sends you back to VCode, signed in. The box shows in the app.

5. The terminal prints Linked to <email>, and Paired with <device> when the site names one.

A browser that is signed in to VCode already signs out of it first, then goes to fezu.dev's link page. If fezu.dev is logged in, the page shows the box name and "Connect to <email>"; tap Connect, or "Use another account" to log in to another one. The app then signs in to the account the box linked to, so the app and the box always end on the same account. A browser on an account with no email (an older trial) adds its email first (free-trial), then goes on the same way. The link waits 15 minutes, as long as the terminal does; after that the app forgets it.

When you paste the code on the terminal instead, the app's own login never finished, so v-code box link signs the desktop app in after Linked to <email> (Opened the VCode app.).

On a box with no browser (a server over ssh), open the printed address on any device instead. The page shows a code with Copy; paste it into the terminal and press Enter. With no browser to open, the first line is Go to <address> on any device, and paste the code it shows here:.

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:

v-code box link on a box already linked prints Already linked to <email> and links nothing. On a box linked to an email with the desktop app installed, it then opens the app signed in to that account, as v-code box app does, and prints Opened the VCode app.; when the site refuses, it prints Could not sign the app in: and the reason, and opens nothing. Running the install command again on a linked box does the same after its Already linked to <email> line. A box removed on your account page (revoked) links again.

v-code box app and v-code alone on a box that is not linked, or one removed on your account page, run v-code box link. On a box still linked to an older trial account (v-code box status reads Linked: yes, trial account) they run v-code box trial instead. The site gives no new start links now, so it prints Could not get a new start link: <the site's reason>. This computer stays on its trial account: open https://app.fezu.dev on a device signed in to it, or run v-code box trial again later. (free-trial).

A refused link prints the site's own message after v-code: and exits 1, for example v-code: 409 this box is linked to another account; unlink it first. A pasted line that is not a code prints That does not look like the code. Paste the code the page shows: and waits for another.

After 15 minutes with no code it stops with v-code: Timed out. Run v-code box link again. With no browser opened and no terminal to paste into, it stops at once with v-code: No browser opened and nothing to paste the code into. Run v-code box link in a terminal.

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 also removes the box from your account, so it no longer counts against your plan's workstations. When fezu.dev cannot be reached or does not take the request, the box still unlinks and the terminal adds fezu.dev did not remove this computer from your account. Remove it on fezu.dev/account.

Options and settings

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. A box that unlinked while fezu.dev was out of reach stays on the account until you remove it on the account page, and cannot join another account until then.
• The settings sheet has no remote access group. Link from a terminal, or with Add a workstation on fezu.dev/account.
• The app or browser opens on macOS, on Windows (also from a box inside WSL) and on Linux with a desktop session. Anywhere else, use the printed address on another device and paste the code.

Related

• add-a-phone: the next step: pair a phone with the box
• add-a-workstation: link and pair in one step with a join code
• free-trial: the 30 days a new account gets, and older trial accounts
• install-on-linux: the one-line install, which runs v-code box link at the end
• desktop-app: v-code box app opens it signed in to the box's account
• use-the-app: what the phone sees on app.fezu.dev
• environment-variables: the box's three variables
• reach-it-from-a-phone: the other ways onto the box: Tailscale or your own tunnel
• synced-settings: a linked box shares its settings and system prompt with the account