Install VCode on Linux with one command

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

curl -fsSL https://v-code.dev/install | sh installs the newest signed release of VCode on a Linux x64 machine, starts it as a systemd --user service, and links it to your v-code.dev account. You need no git, node or npm. The command from "Add a computer" on app.v-code.dev adds a join code, so the box links and pairs with that browser in one step, with no email prompt.

Why you would use it

You want VCode on a server or a spare machine and do not plan to work on its code. The release brings its own node and packages, and it keeps itself up to date (update-automatically). To run from a git clone instead, see install-as-systemd-units.

How to use it

The quickest way starts on app.v-code.dev: open "Add a computer" and copy the command it shows (add-a-computer). It looks like this:

curl -fsSL https://v-code.dev/install | V_CODE_JOIN=<code> sh

Paste it on the machine, logged in as the user VCode should run as. The installer runs as below, but at the end it joins instead of asking for your email: the box links to the account that made the code and pairs with the browser that showed it. That browser then opens the box. The code works once, for 15 minutes; after that, make a new command.

Without a join code:

1. Log in to the machine as the user VCode should run as, over ssh or at the console. Not through su: systemctl --user must answer.

2. Run:

   curl -fsSL https://v-code.dev/install | sh
   

   On a machine with wget and no curl, such as a stock Ubuntu desktop:

   wget -qO- https://v-code.dev/install | sh
   

   The installer then downloads with wget too.

   To pick the port yourself:

   curl -fsSL https://v-code.dev/install | sh -s -- --port 3500
   

3. When it asks, type your v-code.dev email, then the code from the email. This is v-code box link running on your terminal (link-this-box).

4. Pair your phone: v-code box pair (add-a-phone).

The installer has no screen of its own. It runs in the terminal only.

What you see

A first install prints a short summary. Each line starts with v-code:, in order:

• v-code: installing <version>
• v-code: running at http://127.0.0.1:<port>
• v-code: agents: claude, codex, or, with none found: No agent found. Install claude, codex or opencode, then run: ~/.local/share/v-code/current/install.sh install
• with V_CODE_JOIN, the join: v-code: linked to <email>, v-code: paired with <browser name> and v-code: your browser opens it now
• otherwise v-code: to sign in on this machine, use the AUTH_TOKEN in ~/.config/v-code/env, then the link. With a terminal: Link this box to your v-code.dev account: and the Email: prompt. With no terminal: v-code: Link this box: v-code box link. On a box already linked: v-code: Linked to <email>.
• v-code: details in ~/.local/share/v-code/install.log

The steps go to ~/.local/share/v-code/install.log (0600) instead of the terminal. Each run of install.sh install appends to it under a line == <UTC time> install.sh install <version>. The steps are:

• unpacked <version> into ~/.local/share/v-code/versions/<version>, from the download script, above that header
• wrote ~/.config/v-code/env (0600), or on a re-run env file exists, left alone: ~/.config/v-code/env
• installed the updater: ~/.local/share/v-code/bin/v-code-update
• wrote ~/.local/bin/v-code and wrote ~/.local/bin/portal
• one rendered … line per unit
• what systemctl --user prints while it enables and restarts the units, such as Created symlink …
• skipped v-code-tunnel: TUNNEL_TOKEN is empty in <env file>. Fill it in, then run: install.sh install

When a systemctl --user call fails, the install stops with systemctl --user <arguments> failed; see ~/.local/share/v-code/install.log, and its message is in that file.

A link that fails prints v-code: The link did not complete. Try again with: v-code box link. The box runs either way. A free account gets the site's own refusal; linking needs premium.

A join that fails prints The join did not complete: <reason> and Make a new command under Add a computer. The box is installed and runs either way. The reasons you may see:

• that code is wrong, used or expired; make a new command under Add a computer
• this box is linked to another account; unlink it first
• the site's answer does not match this join code

On a box already installed. The same command with V_CODE_JOIN only joins. It prints v-code: already installed: <version>; joining, then the join lines. Nothing is downloaded, so it works while dl.v-code.dev is down. No unit is rendered or restarted, so agents running on the box carry on, even when a newer release is out; the updater installs that one when the box is idle. A box linked to the same account keeps its link and gains the browser.

When the installed release is from before the join, the command installs the newest release instead and joins at the end of that install. It prints v-code: the installed release predates the join; installing <version>. That install restarts the units, so a turn an agent is running on the box stops. When no newer release is out, it stops with v-code: this release does not support V_CODE_JOIN.

On a box installed before the rename to VCode. Releases from before 2026-09-26 run as portal-workbench-prod.service and read ~/.config/claude-portal/env. Their updater never moves such a box to a newer release: it reads latest.json, which stays at the last of them. Run the install command once. It installs the newest release as it would over any older one, and that release's install.sh install moves the env file, the state, the units and their drop-ins to the new names. The threads, the AUTH_TOKEN, the box's link and its paired devices stay. From then on the box updates itself again. With V_CODE_JOIN, the command installs the newest release first and joins at the end of that install, printing v-code: the installed release predates the rename to VCode; installing <version>. When no newer release is out, the installed release joins as it is.

When the old updater died part way through a switch, the command stops before it changes anything: v-code: an update from before the rename to VCode has not finished: run ~/.local/share/v-code/bin/v-code-update --update first, then this again. That runs the old updater, which settles its own switch. Then run the install command again.

Run it from a terminal, not from a thread or the shell panel of the box it moves: the move stops that unit. Inside it, the command stops before it downloads anything: v-code: this is running inside portal-workbench-prod.service, which the move to VCode stops part way through. Nothing was changed. Run the install command from a terminal outside VCode: ssh, or a desktop terminal.

After the move, the release from before the rename is not one to go back to by hand. Its install.sh writes a fresh env file at the old path with a new AUTH_TOKEN, and starts the old units on empty state.

Other lines you may see:

• warning: tmux not found, so the shell panel is off. Fedora: sudo dnf install tmux, Debian: sudo apt install tmux
• note: ~/.local/bin is not on PATH in this shell; a new login shell usually adds it
• warning: Could not turn on linger, so VCode stops when you log out. Run: sudo loginctl enable-linger <user> — see Limits below.
• v-code: VCode did not answer on http://127.0.0.1:<port> within 60 s. See: journalctl --user -u v-code
• v-code: already installed: <version> (the newest release is <version>), then v-code: to run its installer again: ~/.local/share/v-code/current/install.sh install. A re-run never installs an older or equal version. A re-run that installs a newer one keeps the release it replaced and removes any older one, except the one VCode runs; when VCode does not answer it removes none: v-code: could not ask VCode which version it runs, so no old release is removed this run. A re-run after an update that died part way settles that update first, as the updater would.

The checks that stop the install before anything is written:

And the checks on the release itself, which install nothing when they fail:

• signature check failed for releases/<version>/manifest.json: <ssh-keygen's message>
• download does not match the signed manifest: sha256 <got>, signed <signed>
• download is longer than the signed manifest's <size> bytes
• stable.json names <a> but its signed manifest is for <b>
• another install or update is running; try again when it has finished

With V_CODE_JOIN, a release whose install.sh features does not list join stops the run with v-code: this release does not support V_CODE_JOIN. The release is left unpacked under versions/, but current does not move and its installer does not run; run the plain command, or wait for a newer release.

Options and settings

The port pick binds each port on 127.0.0.1 with the release's node. 3446 is skipped because it belongs to the voice sidecar, running or not. With no port free the install stops: no free port from 3445 to 3499; pass --port N.

Where everything lives:

~/.local/share/v-code/
  versions/<v>/            one unpacked release (at most the current one and the last good one)
  current -> versions/<v>  the units run from here
  bin/v-code-update        the updater the hourly timer runs
  update-state/            installed, pending, rejected, agent-dirs
  install.log              what each install did, step by step (0600)
~/.local/bin/v-code        runs current/node/bin/node current/bin/v-code
~/.local/bin/portal        the same, under the name from before the rename
~/.config/v-code/env       AUTH_TOKEN, VCODE_PORT and the rest (0600)
~/.local/state/v-code/     threads, the box's key, voice files

Commands on an installed box:

Limits and known gaps

• Linux on x86_64 with systemd --user only; no Linux on arm64. The same command installs on a Mac, with launchd instead of systemd (install-on-macos). On Windows, see install-on-windows: it runs this installer inside WSL2.
• Linger. Without it the user manager, and VCode with it, stops when you log out. The installer runs loginctl enable-linger <user>. logind asks polkit before it lets a normal user change that, so on a minimal server or a container without polkit it is refused. The install carries on and prints the sudo loginctl enable-linger <user> line; run it once.
• The installer does not install agents. Install claude, codex, opencode or cursor-agent, then run ~/.local/share/v-code/current/install.sh install so the unit's PATH finds it. It looks on PATH, beside nvm's node, in ~/.opencode/bin, and in ~/.local/bin, where claude's own installer puts claude.
• install.sh from a release refuses to run unless current points at that release: install through get-v-code.sh: current does not point at this release (<dir>).
• --port applies only when the env file is new. To move an installed box, edit VCODE_PORT in the env file and run install.sh install.
• cloudflared is needed only when you set TUNNEL_TOKEN.

Related

• update-automatically — how the box keeps itself up to date
• add-a-computer — the command with the join code
• link-this-box — the link the installer runs at the end
• add-a-phone — the next step after linking
• install-as-systemd-units — the same units from a git clone
• install-on-windows — the same box on Windows, inside WSL2
• install-on-macos — the same command on a Mac, with launchd
• environment-variables — what the env file holds
• logs-and-troubleshooting — the journal