The VCode desktop app

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

The desktop app is VCode in its own window on Windows, Linux and the Mac. It shows the same app as app.fezu.dev, and adds a tray icon, start at login, notifications and its own updates. The install command installs it on any computer with a desktop.

Why you would use it

You work at a computer and want VCode one click away, not lost among browser tabs. You also want to hear when a thread finishes or needs you while the window is hidden.

How to use it

With a workstation. Run the install command on a computer you are logged in to at its desktop (install-on-linux, install-on-macos, install-on-windows). The command installs the app as well as VCode itself. At the end the app opens:

on a computer not linked to an account yet, the app opens on its login card, which reads Create an account or log in to connect <computer>. We send a code to your email. Type your email, click Continue and enter the code the email brings. The computer is linked to that account, and the app comes back signed in with the computer in it (use-the-app);
on a computer still on an older trial account, the app opens on that account (free-trial);
with a join command from Add a workstation, the app opens signed in to the account that made the code (add-a-workstation);
on a computer already linked to your account, the install says Already linked to <email> and the app opens signed in to that account;
when the app cannot open, the browser opens the login card instead, and the app stays closed. Open VCode from the Start menu, the app menu or ~/Applications later and sign in with your email and the code it sends.

Sign the app in from the workstation. On a computer linked to your account, run:

v-code box app

It prints Opened the VCode app. and the app opens signed in to the account. v-code alone does the same, and so does v-code box link after Already linked to <email>. Where the app is not installed, v-code box app opens app.fezu.dev in the browser instead. If the site refuses, it prints Could not sign the app in: and the reason, then opens the browser. On a computer that is not linked, v-code box app and v-code run v-code box link, which opens the app on its login card (link-this-box).

The app alone. On a computer that should not run agents, install only the app:

On fezu.dev/account, open Add a workstation, pick the computer's system, and tick App only (#add-app-only). The link /account/add?app=only opens the page with it ticked.
Tap Copy (#add-copy). Each tap makes a new start code and puts it in the command. The code works once, within 5 minutes.

Paste the command into a terminal on that computer (PowerShell on Windows). For Linux and the Mac it reads:

curl -fsSL https://fezu.dev/install | V_CODE_APP=only V_CODE_START=<start code> sh

and for Windows:

$env:V_CODE_APP='only'; $env:V_CODE_START='<start code>'; irm https://fezu.dev/install.ps1 | iex

The app opens, signed in to your account. A code that has expired leaves the app on its sign-in screen.

In the app in a browser on a computer, the install button (#install) opens the Finish onboarding screen with the same command, Copy command (#is-go) making the start code (install-on-a-phone).

Every day.

Closing the window hides it. The tray icon brings it back; on the Mac, the Dock does. The tray menu has Open VCode, Start at login and Quit VCode.
The app starts at login, hidden in the tray, from its first run. Untick Start at login in the tray menu to stop that.
Links to other sites open in your browser. The app and the fezu.dev sign-in pages stay in the window. So does a preview's Open preview: the page opens in your browser.
Right-click a text field for Cut, Copy, Paste and Select All, with spelling suggestions first on a misspelled word. Right-click selected text for Copy, and a link for Copy link address.
On Linux and Windows the window has no menu bar, so Alt shows nothing and every Ctrl shortcut reaches VCode. On the Mac the menu bar has the VCode, Edit and Window menus; Cmd+W, Cmd+= and Cmd+- are VCode's own (close tab, zoom).
Ctrl+R (⌘R on a Mac) renames the tab you are in, where a browser would reload the page.
On Windows and Linux the app's top row is the title bar, in the app's dark colour: the minimise, maximise and close buttons sit at its right end. Drag the row to move the window; on the Log in screen, drag the top edge. In a narrow window the buttons get a dark strip of their own above the meters. On Linux maximise turns into restore while the window is maximised. The Mac keeps its own title bar, dark even when the Mac is in light mode.
Turn notifications on with the bell (#notify), as in a browser (turn-on-notifications). A notification shows while the app runs, window hidden or not. Click it to bring the window up on that thread.

What you see

Every line from the app step starts with VCode desktop app:.

VCode desktop app: installed <version>, or VCode desktop app: <version> is installed when nothing newer is out.
VCode desktop app: opening VCode when the command installs the app alone.
VCode desktop app: open VCode from the app menu on the desktop when you install the app alone over ssh on a Linux computer with a desktop session: the app is installed, but cannot open from there.
VCode desktop app: no desktop session; skipped on a computer with no desktop, such as a server reached over ssh.
After a trial or a join in the same run, the box's line Opened the VCode app. After a link, the box's line Opening VCode to connect this computer….
A failed app step prints one line with the reason, ending in ; the box is installed. VCode itself is installed and linked as usual.
With V_CODE_APP=only there is no box to fall back on, so a failed app step, or no desktop session, fails the command. On Windows its last line is v-code: the desktop app is not installed.

The command stops before it installs anything when:

Check	Message
`V_CODE_APP` is `no` or `only`	`v-code: V_CODE_APP is <value>; it must be no or only`
`V_CODE_START` comes with `V_CODE_APP=only`	`v-code: V_CODE_START is for V_CODE_APP=only`
`V_CODE_START` is a start code	`v-code: V_CODE_START is not a start code; copy the command again`
`V_CODE_APP=only` comes without `V_CODE_JOIN` or `--port`	`v-code: V_CODE_APP=only installs the app alone; V_CODE_JOIN and --port are for the box` (on Windows: `v-code: V_CODE_APP=only installs the app alone; V_CODE_JOIN is for the box`)

Linux: the sandbox question

On a Linux computer that restricts user namespaces, such as Ubuntu 23.10 and later, the window needs one AppArmor rule to run sandboxed. The command asks once:

The VCode window needs one AppArmor rule to run sandboxed. Add it with sudo? [Y/n]

Yes (or Enter) asks for your sudo password, adds the rule and prints VCode desktop app: added the AppArmor rule /etc/apparmor.d/v-code-desktop. Later updates never ask again.
No, no terminal to ask on, or a failed sudo: the app runs without the browser engine's sandbox, and the command prints VCode desktop app: runs without the Chromium sandbox (no AppArmor rule). The next run of the install command asks again.

The Mac and Windows

The app is not signed by a publisher on any system. The install command downloads it, not a browser, so the file carries no download mark. On Windows that means no "Unknown Publisher" prompt; the same file downloaded with a browser shows one. On the Mac curl sets no quarantine flag, and the command clears one if it is there.
On the Mac the command signs the app for this Mac itself (ad hoc) before it moves it to ~/Applications/VCode.app: renaming Electron's app as VCode breaks Electron's own signature.
On Windows the app is in the Start menu as VCode.

On the box's own PC

When the app runs on the same computer as a workstation, it talks to that workstation directly on the computer, without going through fezu.dev. The tab badge then reads <box name> · local. There is nothing to set up: the app and the workstation agree on it each time the app connects. If the direct way fails, the app keeps working through fezu.dev, as on any other computer, and tries again 5 minutes later. A browser on the same computer always goes through fezu.dev.

Options and settings

Option	Default	What it changes
`V_CODE_APP=no`	unset	The install command installs VCode without the desktop app
`V_CODE_APP=only`	unset	The command installs only the desktop app, no workstation, and opens it
`V_CODE_START=<code>`	unset	With `V_CODE_APP=only`: the start code that signs the app in. Copy on Add a workstation and Copy command in the app put one in
Start at login (tray menu)	on	Starts the app hidden in the tray when you log in

Limits and known gaps

Beta. A Windows build was tried on a Windows 11 virtual machine. The Mac build has not yet been tried on a real Mac.
x64 only on Windows and Linux: on a Linux ARM64 box the install skips the app. The Mac has builds for Apple silicon and Intel.
Notifications reach the app only while it runs. Quit from the tray, it gets none until it starts again; start at login keeps it running.
On a Linux desktop with no tray (GNOME without the AppIndicator extension) closing the window quits the app, since nothing could bring it back.
The app does not follow the account's channel. Switching Stable or Dev on fezu.dev/account moves the box, not the app; run the install command again with V_CODE_CHANNEL to move the app.
The install command installs the app; the hourly box updater does not. A computer installed before the app existed gets it the next time you run the install command there.
In the app, the Finish onboarding screen and the install button are hidden.

Updates

The app checks for a new version 30 seconds after it starts, every time you launch it again while it runs in the tray, and then every hour (every 5 minutes on the dev channel). It downloads and checks the new version while you work. Once it is ready:

With the window closed to the tray, the app restarts into it at once.
With the window open, the update button in the top bar (#update-ready) reads "Update ready: restart". Tap it to restart now. The window comes back where it was, maximized or not.
Otherwise the app restarts by itself after 5 minutes with no typing or clicks (at once on the dev channel). A window that sat behind other windows comes back behind them. A minimized window waits, and so does one you brought back less than 5 minutes ago.
A restart keeps no half-written messages, so words in any tab's composer, an unsaved file edit, a dictation or typing hold it, closed to the tray too.

The version before stays on disk.

Remove it

The box's uninstall removes the app too:

Linux and the Mac: ~/.local/share/v-code/current/install.sh uninstall. It quits the app if it runs, then removes it, its menu and autostart entries, and its start link. The AppArmor rule is root's, so it stays; the command prints the line that removes it.
Windows: $env:V_CODE_UNINSTALL=1; irm https://fezu.dev/install.ps1 | iex. It stops the app and removes it, its Start menu entry and its start at login.

The app's own settings folder (channel, log) stays, as the box's env file does. Its state goes, so an install after it starts the app at login again.

install-on-linux: the command that installs it with a workstation
install-on-macos: the same on a Mac
install-on-windows: the same on Windows
free-trial: the 30 days a new account gets, and older trial accounts
link-this-box: v-code box link, which opens the app's login card
add-a-workstation: the join command and App only
turn-on-notifications: the bell, in the app too
where-notifications-work: the app's row
install-on-a-phone: Finish onboarding, which shows the app's command on a computer
release-channels: stable and dev
app-page-views: the count the app sends when it opens