Truy cập từ xa

Connect a phone, browser, or another desktop app to VC running on a different machine. That machine must stay running and reachable while you work.

Open a computer from your account portal

Sign in to the account portal, open Computers, and choose Control next to your environment. VC opens in a new browser tab and signs in with the portal’s account. Registered computers use VC Connect when linked, or a reachable HTTPS address. A private-network address works only when your browser can reach that network. The list’s update time records registration, not whether the computer is online; the control tab checks the connection when you open it.

The tab provides the environment’s projects, agents, terminal, files, Git and connection settings with owner permissions. Tools that need desktop or operating system permissions still require support on the host. Keep the host updated to use owner permissions through VC Connect.

Work stays on the host. When disconnected, reconnect before sending new commands. Closing the tab does not stop an agent; use its stop action in VC. Signing out or changing accounts removes account-linked connections from that browser and ends their sessions on the host. If the host was unreachable then, revoke the browser in Settings → Connections on the host. Without VC Connect, this access expires after 30 days. Open the computer from the portal again to reconnect.

VC Connect

VC Connect makes an environment available to your other devices without setting up router forwarding. In the desktop app on the host, open Settings → Connections, sign in, and enable VC Connect for that environment.

For a command-line host, run:

npx vc@latest connect

Follow the sign-in instructions. Setup offers a background service; if you decline it, start the server with npx vc serve. Saving your sign-in alone does not make the machine reachable.

On your other device, sign in to the same VC Connect account and choose the environment. Over SSH, the CLI prints a browser link and accepts the returned authorization code, so you do not need to forward an OAuth callback port.

VC Connect renews access credentials when needed without disconnecting a healthy connection. Pull request diffs and provider settings keep working after the previous credential expires. A failed renewal affects that request; it does not disconnect an otherwise healthy conversation.

Your own Cloudflare Tunnel

If you have a domain on Cloudflare, you can reach an environment through a tunnel in your own Cloudflare account instead of VC Connect, at an address you choose such as https://vc.example.com. See Cloudflare Tunnel for setup and troubleshooting.

Pair over a LAN or private network

Use direct pairing when the other device can reach the host’s network address.

On a desktop host, open Settings → Connections, enable Network access, then create a pairing link using an address the other device can reach. Changing network access restarts the desktop app. You can turn it off in the same place.

For a command-line host, replace <private-ip> with the host’s LAN or tailnet address:

npx vc serve --host <private-ip>

If a server is already running, generate a fresh link without restarting it:

npx vc pair

Scan the QR code on your phone or paste the pairing URL into Add environment in the receiving app. Open it from the environment menu above the thread list, or on web and desktop from the command palette. Connection settings are under Settings → Connections on web and desktop and Settings → Environments on mobile. A loopback address such as 127.0.0.1 reaches only the device opening the link.

The web client needs your VC account as well as the pairing. A link created in Settings → Connections while you are signed in also signs the browser in to your account, so share such links only with your own devices. A link limited to selected projects never does; see Share selected projects. A link used after its first sign-in, or created while signed out, asks again: choose Open portal, sign in there, and paste the one-time code it shows. Signing out returns you to this step; the pairing is kept.

Pairing authorizes that device for future connections. Use a fresh one-time link for each new device; you do not need the original token to reconnect. Links created in Settings can only be copied from the client that created them while its Connections page stays open. If you leave or reload that page, create another link to share.

New pairings remain authorized across updates and restarts until you revoke the device in Settings → Connections. Clearing client data or browser cookies requires pairing again. A pairing issued by an older version can retain its original expiry and may need to be replaced once. Separately issued tokens keep their configured expiry; VC Connect renews its short-lived credentials automatically.

Balance new threads across machines

Auto balance is off by default. On web and desktop, enable it in Settings → Connections → Load balancing to automatically choose a machine for new threads in projects grouped across connected environments. Each machine starts at Normal. Choose Prefer to favor it when it has CPU and memory available, Less often to reduce its share, or Manual only to exclude it from automatic selection. These are preferences, not fixed traffic percentages. Preferences are saved separately in each client.

The composer checks eligible machines when choosing a draft’s environment, then keeps that choice stable. Choose Auto balance again to check current resources, or choose a specific machine to override it. Choosing a branch or worktree also keeps the draft on that machine. Existing threads stay where they started. If resource checks are unavailable or all eligible machines are full, choose a machine manually to continue. Mobile keeps its manual environment selection.

Tailscale HTTPS

Join both devices to the same tailnet. In the desktop app, enable Tailscale HTTPS in Settings → Connections. Turn it off there to remove that route.

To start a command-line server with Tailscale HTTPS:

npx vc serve --tailscale-serve

For an already-running server:

npx vc pair --tailscale

The pairing link uses an address such as https://machine.tailnet.ts.net/. The mapping created by pair --tailscale persists across restarts. Remove its default-port mapping with:

tailscale serve --https=443 off

If that port is already in use, choose another with --tailscale-serve-port. See npx vc pair --help for other pairing options.

Hosted web app

app.vce.codes needs an HTTPS endpoint. It connects directly to your server; a hosted pairing link does not make an unreachable backend reachable or convert HTTP to HTTPS.

For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can open it, or pair from the desktop app. On mobile, an IP address entered without a scheme uses HTTP, so include https:// when your server uses HTTPS.

Preview a remote project

Open your computer from the Portal, select a project, and open Preview. Start its dev server in a VC terminal, then select the detected server or enter an address such as localhost:3000. The address refers to the environment’s computer. Web and remote desktop clients can interact with the page, including live reload, WebSockets and streaming responses.

VC authorizes detected ports belonging to that project together, so a web app on port 3000 can call its API on port 8080. Start both before opening Preview. If ownership cannot be detected, an environment administrator can add the ports under Preview → Ports. That dialog also lists active exposures and lets you revoke them. A port known to belong to another project cannot be added this way. Preview requires permission to operate terminals in the environment.

VC Connect routes Preview automatically. LAN connections use additional ports; allow them through the host firewall if necessary. Tailscale uses HTTPS port forwarding, and desktop SSH connections forward preview ports automatically. Older hosts or Connect endpoints may require an update before Preview is available; the rest of the VC connection remains usable.

If the browser blocks embedded cookies, use the preview’s storage-access prompt or open it in a separate tab. Preview access expires with your environment session and stops when you revoke access, stop the exposure, or delete its project. Keep the host and dev server running.

Public websites load directly and may require a separate tab if their embedding policy blocks Preview. Project pages with a restrictive script policy show limited mode: page interaction still works, but localhost rewriting, the element picker and agent automation may be unavailable. Web Preview supports zoom, viewport sizes, the mini player and recording started by you; use your browser’s DevTools to inspect it. Screenshot capture, native device emulation and separate browser profiles require desktop support.

Localhost addresses embedded in static assets and OAuth callback URLs are not rewritten. Configure those in the project when they need a remotely reachable address. Native mobile Preview is not supported.

Desktop-managed SSH

In the desktop app, open Settings → Connections → Add environment, choose Connect with SSH, and enter a host or SSH config alias. Supply a username and port if your SSH config does not already set them. VC starts or reuses a server there and opens the port forward for you. Projects, provider credentials, and agent work stay on the remote machine.

Use an SSH key or agent; this connection does not prompt for passwords. Connect from a terminal once to verify and trust the host before adding it to VC.

The remote host needs a compatible Node.js installation and provider setup. If launch cannot find Node or reports an incompatible version, check it through a non-interactive SSH session:

ssh [email protected] 'sh -lc "command -v node && node --version"'

Configure your version manager for non-interactive shells if this differs from your normal terminal. With nvm, setting a compatible default, such as nvm alias default 24, can resolve the problem.

If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that VC launched; a server that was already running is left alone.

For Antigravity’s Google callback on a remote host, see remote sign-in.

Keep messages up to date

VC automatically keeps active and recent conversations synchronized, including when you switch to another conversation or leave the web or desktop window in the background. Your environment must stay running and reachable. If your browser suspends the tab, VC catches up when it resumes.

On mobile, leave VC and it keeps syncing while the operating system allows. Android stays connected and shows a quiet notification you can stop. iOS syncs for a short time, then refreshes again when the system runs background work. Turn this off in Settings → Background Sync. Force-closing the app stops it. Reopening VC catches up on messages missed while it was suspended.

Agent notifications

On iOS and Android, sign in to VC Connect, link your environment to that account, and enable Settings → Device Notifications. VC can notify you when an agent needs approval or input, finishes, or fails. The environment must remain running and publish activity to the relay. Opening a notification takes you to its task. These pushes do not require Background Sync to stay connected. Live Activities remain available only on supported iPhones. On Android, enabling notifications also links your locally paired environments to your account.

Work from mobile

Open Settings → Tools on your phone and select an environment. Select a project to create and edit tasks, respond to approvals, add comments, or save and run HTTP requests. HTTP requests run on the selected environment, so they can reach services on that machine’s network. Saved credentials are retained when editing requests; manage authentication and import collections on web or desktop.

Inbox, listening ports, and Docker are available without selecting a project. Enable Docker Manager for the environment in Settings → Integrations on web or desktop first. Mobile can manage containers, remove images and volumes, and view container logs. Log streaming pauses when you leave the screen or put the app in the background.

Manage or revoke access

On the host, Settings → Connections lets authorized administrators create pairing links, issue scoped bearer tokens for headless clients, and revoke client sessions. Revoking an unused link prevents new pairings; revoke a device’s session to remove its existing access. Command-line management is available through npx vc auth --help.

A session with an open connection stays listed after its access credential expires.

To remove an environment from VC Connect, open your account menu’s VC Connect page, or Settings → VC Connect on mobile, and choose Deregister. This revokes its cloud access and frees its host space even when the environment is offline or has been wiped.

On a command-line host, vc connect unlink disables exposure while retaining your login; vc connect logout also clears that login. Background-service removal is separate.

Treat pairing URLs and authorization codes as passwords. Do not include them in screenshots, logs, or bug reports.

VC Connect troubleshooting

Run vc connect status on the host to inspect saved authorization and link configuration. It is not a live reachability check. If the environment appears offline, run vc service status and read the displayed log. If it disappears when SSH closes, see background-service troubleshooting.

After fixing a permanent rejection, restart the host’s server. On Linux, use systemctl --user restart vc.service for the background service. For a foreground server, stop it and run vc serve again with your usual options. Include the diagnostic message and trace ID when reporting a persistent failure.

For a connection that still fails after linking, check the date and time on both devices. For server version warnings, follow Updating VC.

Limit access from a pairing link

In Settings → Connections → Create pairing link, set any combination of:

• Total pairings: successful uses over the link’s lifetime. Revoking a device does not restore a use.
• Paired devices: devices with valid access created by this link. Revoking access or letting it expire frees a slot. Pairing again creates a separate device entry.
• Online connections: connections open at the same time. Each browser tab or window counts separately; disconnecting frees a slot.

Leave a limit empty for unlimited. All configured limits apply independently. Existing links keep their original usage limit, with no device or online connection limit. Expiring or revoking a link prevents new pairings; revoke a paired device separately to remove its access.

From the CLI, both vc pair and vc auth pairing create accept --max-uses, --max-devices, and --max-concurrent-connections. Use 0 for unlimited, for example vc pair --max-uses 0 --max-devices 5 --max-concurrent-connections 2.

Share selected projects

To let someone else work in some of your projects, open Settings → Connections → Create pairing link and turn on Only selected projects, then pick the projects. A device paired with that link:

• sees and works only in those projects: their threads, files, Git, and, if you allow it, terminals;
• cannot add or change projects, or reach your settings, provider accounts, usage, other projects, or files outside the shared projects through VC;
• does not sign in to your VC account. On the web, the other person signs in with their own account.

Operate tasks and Use terminals still run on your computer under your account. An agent or terminal can read anything your account can, so someone allowed to use them could ask an agent for files outside the shared projects. Give those permissions only to people you trust; choose Read only otherwise.

The pairing link and each paired device show which projects they reach. Revoke the device in Settings → Connections to end its access.