# Set up VcodeR — one-link agent runbook

VcodeR lets the user leave a computer online at home and work from the browser or Quest Browser. Set up the host on **their computer**. Detect the OS and agent before choosing commands. The Codex bridge is the established public alpha path. The new MCP bridge is an assignment-loop beta for local coding agents that support MCP over stdio. Native Windows scripted MCP tests have passed approval, assignment, worktree creation, result reporting, and cancellation. Claude Code and Cursor CLI have each set up from this public link and completed real tasks across client restarts through the public production service on macOS. Unrelated external-user acceptance remains open. Do not claim that every agent already works.

## Support and acceptance

- macOS + Codex: fresh production account, actual code task and restart verified.
- Windows 11 + Codex: public-link setup on a fresh native Windows VM, normal browser approval, a real production coding task and continuation after connector restart verified. All three initial tests and four post-restart tests passed, including a native win32 assertion; tests were independently rerun. An 80-second scoped network interruption also recovered automatically and delivered a queued task in the same conversation. Node, Git and the coding agent were installed and signed in before the one-prompt setup trial.
- Claude Code MCP: public-link configuration, normal browser approval, two real production coding tasks across a client restart, and independently rerun tests passed on macOS.
- Cursor CLI MCP: the same public-link, browser approval, production task and restart checks passed on macOS. Cursor editor UI setup is not separately verified.
- Ubuntu 24.04 Linux + Codex: native public connector approval, real production coding tasks and continuation after connector restart passed; independent tests passed 3/3 then 4/4. A fresh setup agent downloaded and verified the public bundles, but activation required the normal terminal command because its nested sandbox made provider state read-only. Fully independent one-prompt Linux activation, other distributions and Linux desktop control remain unverified. Linux hosts must be kept awake by normal OS/server configuration.
- Other agent stacks: unverified; never infer a pass from tool discovery or a scripted MCP test.
- Full desktop control and Windows remote app previews are outside this coding-connector setup.

## Before you start

- macOS, Windows 11, or Ubuntu Linux, Node.js 22 or newer, Git, and a host that can remain powered and online.
- A VcodeR account: https://vcoder.78-46-232-79.sslip.io/?signup=1
- On Linux, the coding agent needs its normal sandbox prerequisites. For Codex, install the distribution `bubblewrap` package. Restricted Docker containers may prevent its namespace sandbox from running; prefer a native host or VM. On Ubuntu 24.04, follow the official bubblewrap AppArmor profile guidance rather than disabling host protections: https://learn.chatgpt.com/docs/sandboxing#prerequisites
- A coding agent signed in locally to its own provider. For Codex, run `codex login` on macOS or `codex.cmd login` in Windows PowerShell if needed.
- Never ask the user to paste account passwords, API keys, browser approval secrets, or verification codes into chat. The user signs in and approves in their browser. When running through SSH or another headless session, do not assume a spawned desktop window is visible: keep the connector in a real interactive terminal or use the terminal approval link. Do not save approval links or codes in logs.

## 1. Download and verify both host bridges

### macOS / Linux terminal

```sh
mkdir -p ~/Downloads/vcoder
curl -fsSL -o ~/Downloads/vcoder/vcoder-connect.mjs https://getvcoder.com/downloads/vcoder-connect.mjs
curl -fsSL -o ~/Downloads/vcoder/vcoder-mcp.mjs https://getvcoder.com/downloads/vcoder-mcp.mjs
curl -fsSL -o ~/Downloads/vcoder/SHA256SUMS https://getvcoder.com/downloads/SHA256SUMS
cd ~/Downloads/vcoder
# Linux: sha256sum -c SHA256SUMS
# macOS: shasum -a 256 -c SHA256SUMS
```

### Windows PowerShell

Use native Windows Node, Git and Codex, not a mixture of WSL and Windows executables. Node's installer and Git for Windows must already be available before running these commands.

```powershell
$vcoderDownloads = Join-Path $env:USERPROFILE "Downloads\vcoder"
New-Item -ItemType Directory -Force $vcoderDownloads | Out-Null
foreach ($name in @("vcoder-connect.mjs", "vcoder-mcp.mjs", "SHA256SUMS")) {
  Invoke-WebRequest ("https://getvcoder.com/downloads/" + $name) -OutFile (Join-Path $vcoderDownloads $name)
}
foreach ($line in Get-Content (Join-Path $vcoderDownloads "SHA256SUMS")) {
  $parts = $line -split "\s+", 2
  if ($parts.Count -ne 2 -or $parts[1] -notin @("vcoder-connect.mjs", "vcoder-mcp.mjs")) { throw "Unexpected checksum entry" }
  $actual = (Get-FileHash (Join-Path $vcoderDownloads $parts[1]) -Algorithm SHA256).Hash
  if ($actual -ne $parts[0]) { throw ("Checksum mismatch: " + $parts[1]) }
}
node (Join-Path $vcoderDownloads "vcoder-connect.mjs") --check
node (Join-Path $vcoderDownloads "vcoder-connect.mjs") --discover
```

The preflight reports OS, Node, Git and Codex login readiness without printing credentials. In Windows PowerShell, use `codex.cmd` if the npm `codex.ps1` shim is blocked by execution policy; do not weaken the machine execution policy. If Codex is missing, install it from its official distribution and run `codex.cmd login` in Windows PowerShell (or `codex login` on macOS); complete any required login in the browser. Do not copy another machine's credentials. Windows worktrees live under LOCALAPPDATA/VcodeR/worktrees. Keep the connector terminal open; reopening the same command restores the connection. If a Linux setup agent reports that its nested sandbox makes Codex provider state read-only, start the verified connector command in a normal terminal, outside that nested agent shell. Keep coding-task permissions in effect; do not disable the sandbox to make setup pass.

Stop if either checksum fails. These are Node scripts, not native installers. Read the bridge you are about to run. Install only the prerequisites needed for the selected adapter, preserve existing configuration, and use the chosen project scope. Ask only for missing access or required user-controlled consent.

## 2A. Codex bridge — established public alpha

Codex CLI must be installed and signed in. To import existing Codex conversations:

```sh
node ~/Downloads/vcoder/vcoder-connect.mjs --discover
```

For a Git project with at least one commit:

```sh
node ~/Downloads/vcoder/vcoder-connect.mjs "/absolute/path/to/project"
```

On Windows PowerShell, use the native path equivalent:

```powershell
node (Join-Path $env:USERPROFILE "Downloads\vcoder\vcoder-connect.mjs") "C:\path\to\your\project"
```

Replace the example with your actual Git project. The connector opens browser approval. The user signs into the same VcodeR account and approves the device. Leave the connector running. On macOS and Windows it prevents **idle** sleep while running; Linux hosts must be kept awake by their normal OS or server configuration; closing the lid, quitting the process, or losing network still disconnects the host.

## 2B. MCP bridge — beta for stdio-capable local agents

Use this only if the user's agent supports a local stdio MCP server and can keep its client session running. Choose a Git project with at least one commit. Configure the agent's MCP server named `vcoder` with an absolute Node path and the downloaded bundle, for example:

```json
{
  "mcpServers": {
    "vcoder": {
      "command": "/absolute/path/to/node",
      "args": ["/Users/NAME/Downloads/vcoder/vcoder-mcp.mjs"],
      "env": {
        "VCODER_AGENT_WORKSPACE": "/absolute/path/to/git/project",
        "VCODER_AGENT_NAME": "My coding agent",
        "VCODER_AGENT_PROVIDER": "my-agent"
      }
    }
  }
}
```

Replace every example path with a verified local path. Put the MCP config in the user's chosen agent scope; do not silently modify global configuration. Restart or reload the agent client so it starts the server. On macOS and Windows the server prevents host idle sleep while it runs. Linux hosts must be kept awake through their normal OS or server configuration.

### Named-client setup

- Claude Code: add the `vcoder` entry to this project's `.mcp.json`, preserving all existing servers. In the Claude Code session, approve the server and use the assignment prompt below.
- Cursor: add the same entry to this project's `.cursor/mcp.json`, preserving existing servers. Reload that project's MCP tools, approve VcodeR, then use the assignment prompt.
- Use the actual absolute Node executable and connector path on your OS. JSON Windows paths need escaped backslashes or forward slashes. Set `VCODER_AGENT_PROVIDER` to `claude` or `cursor` and a recognisable agent name. Never replace the user's entire config.
- Leave client permissions in effect. Grant only the file and test-command access needed for the selected disposable project; do not disable approval or security protections.

Assignment prompt: “Connect with vcoder_connect. Keep polling vcoder_next_assignment while I use VcodeR. For each assignment, work only in the returned cwd, check vcoder_assignment_status during work, stop if cancelled, and use vcoder_report for actual progress and verified completion. If a permission prevents work, report the blocker instead of claiming completion.”

Call `vcoder_connect`; the user approves in the browser. Then keep the agent session running and have it call `vcoder_next_assignment` to receive headset/browser work. The returned assignment names an isolated Git worktree. The agent works there, checks `vcoder_assignment_status` during long tasks, and calls `vcoder_report` with progress or a final result. The MCP server **does not execute work by itself or make the client poll automatically**. If the agent stops or its MCP server exits, remote work stops until the client is running again. Existing chats from non-Codex agents are not imported.

If the client cannot support this polling loop, say so and use the Codex bridge. Do not call a connected MCP socket a successful end-to-end coding session.

## 3. Prove the first real reply

Open https://vcoder.78-46-232-79.sslip.io/ in a browser with the same account. Send a small real task. Success requires a nonempty reply from the chosen host agent, visible in the same conversation. Record whether approval, first reply, and a host-process restart work without personal help. Do not mark setup complete from an online indicator alone.

Quest 3/3S can open the same workspace in Quest Browser. The native Quest APK is still an owner test build, not a public sideload. VcodeR is not yet verified on Meta VR Glasses or other plug-in AR displays.

## Limits and help

- The computer must remain online and awake with the connector or MCP client running. The sleep assertion does not override lid-close or network loss.
- MCP is a cooperative beta, not an autonomous universal adapter. Test each agent stack independently before claiming support.
- No cloud execution, password recovery, or guaranteed remote app previews yet.
- Manual Codex setup: https://getvcoder.com/downloads/SETUP.txt
- Feedback: https://getvcoder.com/#feedback or hello@getvcoder.com