On Linux and macOS, VC can run as a service for your user so you do not need to keep a terminal open. The desktop app runs its own backend instead, for as long as the app is open.
Desktop app
In the desktop app on macOS, Linux, or Windows, choose Sign in and host, sign in to verify your plan, then select Start my server. Later launches reuse that choice. Connect to a server only connects to an existing server and does not start a local backend. Choosing This computer connects automatically; you do not need to enter a pairing code, including after signing out and choosing it again.
The backend runs only while the app does. It starts when you open the app, is started again if it crashes, and listens on the same port every launch, so paired web and mobile clients reconnect to the same address. Quitting VC, including closing its window or choosing Quit from the tray icon, stops the backend along with its running agents and terminals, and remote clients lose this computer until you open the app again. Quitting while agents or terminals are busy asks you to confirm first; turn that off in Settings → General → Running work on quit. On macOS, quitting from the Dock or logging out skips the question. An app update takes effect at the next launch; it does not restart active agents before then.
A server you started separately for the same data home, such as vc serve or a
vc service install, is reused and keeps its own lifetime. To keep agents
available while the app is closed, run one of those instead. The desktop backend’s
log is userdata/logs/desktop-backend.log in the data home (~/.vc unless you set
VC_HOME).
Manage a published CLI service
Run these commands on the machine that will host VC:
| Task | Command |
|---|---|
| Install and start | npx vc@latest service install |
| Inspect status and log location | npx vc@latest service status |
| Update or repair | npx vc@latest service update |
| Stop and remove from startup | npx vc@latest service uninstall |
Uninstalling the service leaves your projects, threads, and settings intact.
Install and update use the version of the CLI you invoke. For nightly, use
npx vc@nightly service update; replace nightly with an exact version to pin
one. An older CLI refuses to replace a newer service unless you explicitly add
--allow-downgrade.
Updating restarts the server. Finish active work first, and wait for any remote update already in progress. To match a remote client’s version, follow Updating VC.
Platform support
Linux needs systemd user services. Setup enables lingering so VC starts at boot and keeps running after logout. If this needs administrator permission, setup prints a recovery command before changing the service.
macOS starts the service when you log in and stops it when you log out. Keep the Mac logged in and awake for unattended remote access. Installing over SSH while nobody is logged in at the Mac’s screen can fail at the final start step; the service is still installed and will start at the next login.
Windows has no vc service installer. The desktop app runs its own backend
while it is open; pairing to an existing backend works as on any platform.
VC Connect can offer service installation during setup, but the two are managed separately. Signing out of VC Connect does not stop or uninstall the service.
Troubleshooting
Start with vc service status on the host. It prints the log path and, on Linux,
checks whether the installed service is running, enabled, and allowed to survive
logout.
If it stops when your SSH session closes, check for linger-disabled. An
administrator can enable lingering with:
sudo loginctl enable-linger "$(id -un)"
Over SSH, allow sudo to prompt:
ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
Then retry service setup as your normal user. Run only the loginctl command
with sudo; running VC as root creates a separate installation and Connect
identity. Without administrator access, run vc serve in a terminal and keep
that session open.
| Status problem | Next step |
|---|---|
linger-unavailable |
Run loginctl show-user "$(id -un)" --property=Linger and check that systemd-logind is available. |
user-manager-unavailable |
Run systemctl --user status in a login session for the service user; check your distribution’s systemd user-session support. |
service-disabled or service-stopped |
Read the log and systemctl --user status vc.service, then use the repair command printed by VC. |
On macOS, check System Settings → General → Login Items if the service no
longer starts at login. If agent work cannot access Desktop, Documents, or
Downloads, it may need Full Disk Access for the Node executable listed in
ProgramArguments in
~/Library/LaunchAgents/com.vc.app.service.plist.
For failures after signing in to VC Connect, see connection troubleshooting.