# Giving Claude its own computer: a setup guide

*For Remy, and for the Claude that will set this up with him. Written from Xavier's setup, which has been running
daily since late 2026.*

---

## Part 0: For Remy (5-minute read)

### What this is

Claude Code on its own can edit files and run commands. That covers code, but most of life happens in websites
and apps you're signed in to. Give Claude three more things and it can do most of what you can do at a computer:

1. **Its own always-on computer** that it fully controls: admin rights, never sleeps, nobody else using it.
2. **A real, signed-in web browser** that it drives like a person would. This means your actual Chrome with your
   logins, not a "bot browser" that sites can detect and block.
3. **OS-level control** of that computer: screenshots, mouse, keyboard, GUI apps, system settings.

### What it unlocks (real examples from Xavier's setup)

- **Services with no API, or a paid-only API.** Suno: Claude writes the lyrics, generates songs in the Suno
  web app, picks takes and downloads them, all on Xavier's normal subscription. The same goes for most AI image and
  video tools, Canva, and anything else behind a login.
- **Life admin:** paying bills through online banking, filling in applications and forms, booking things,
  checking orders, comparing prices on sites that block scrapers.
- **Sign-in codes:** reading emailed codes (Gmail over IMAP) and SMS codes (Google Messages for web), so it
  can sign in without stopping to ask you.
- **Research behind logins:** LinkedIn, paywalled news you subscribe to, internal dashboards.
- **Heavy jobs off your laptop:** video renders, builds and downloads run on the box overnight, with a big
  external drive for storage.
- **GUI apps and system settings** that have no command line.

### The decision to make first: Mac box or Windows box

**Your own computer's OS doesn't matter.** Claude Code runs on your Windows PC and controls the box over SSH.
The question is only what *the box* runs.

| | Mac mini as the box | Windows mini PC as the box |
|---|---|---|
| Browser layer | **Understudy already exists** (Xavier's tool: real Chrome on a hidden display, MCP server, password vault, audit log). Install takes about an afternoon. | You have to build it. Part 4 is the spec for your Claude to build from, roughly a few days of back-and-forth. Or start with Anthropic's Claude in Chrome extension (Part 4A). |
| OS control | Well-trodden: AppleScript, `cliclick`, `screencapture`, Accessibility APIs. | Workable, but SSH sessions can't see the desktop (Part 3, "the Session 0 problem"). UAC prompts can't be clicked by software. |
| Cost | Base Mac mini | A cheap mini PC or a spare Windows machine |

**Recommendation:** if you're buying hardware anyway, a base Mac mini is the shortest path to everything working,
even with a Windows main PC. If you'd rather use a spare Windows machine, it's very doable. Just expect the browser
layer to be a project rather than an install. The fundamentals below are the same either way.

### What you'll have to do by hand

Your Claude can do almost all of this itself. You'll be needed for:

- Initial OS setup and creating the user account.
- Permission dialogs the OS deliberately won't let software click (macOS privacy toggles, Windows UAC).
- **Signing in to your accounts once** in Claude's browser. After that the sessions persist.
- Saving passwords into the password vault (Claude never sees them; see Part 5).
- Deciding what Claude may do without asking. Part 6 has our rules as a starting point.

---

## Part 1: The architecture (for Claude)

```
 Remy's PC (Windows)                         The box (always on, dedicated to Claude)
 ┌─────────────────────┐   SSH (key auth)    ┌──────────────────────────────────────────┐
 │ Claude Code         │ ──────────────────▶ │ shell: builds, scripts, long jobs        │
 │  - global CLAUDE.md │                     │                                          │
 │  - MCP: browser     │ ── SSH tunnel ────▶ │ browser service (localhost only)         │
 │                     │   (or Tailscale)    │   └─ real Chrome, own profile, signed in │
 └─────────────────────┘                     │ desktop agent (in the logged-in session) │
                                             │   └─ screenshots, mouse, keys, GUI apps  │
                                             │ big disk for outputs                     │
                                             └──────────────────────────────────────────┘
```

Five layers, in order of importance:

1. **A dedicated box with full access.** Claude is an admin there. Its password goes in Claude's instructions so
   it can use sudo or elevation without asking. That's only acceptable because the box holds nothing but Claude's
   work and the browser profile. Don't do this on a shared family machine.
2. **Non-interactive SSH** from the main PC to the box, with key auth, so Claude can run anything there in one
   command.
3. **A browser service** that exposes a real, signed-in Chrome to Claude as MCP tools (`navigate`, `read_page`,
   `click`, `type_text`, `screenshot`, `type_password`, …).
4. **A way to run things inside the logged-in desktop session.** An SSH shell is *not* the desktop on either OS:
   it can't see the screen or drive apps.
5. **A global `CLAUDE.md`** that tells every future Claude session that all of this exists, how to use it, and
   the rules. Without it, each session rediscovers everything or doesn't know it can.

---

## Part 2: The box

### If it's a Mac mini

1. Create a user, enable **automatic login** (System Settings → Users & Groups).
2. Never sleep: `sudo pmset -a sleep 0 displaysleep 0 disksleep 0`. Screen lock and screensaver off, because a
   locked screen blocks GUI input.
3. Remote Login (SSH) on. Put the PC's public key in `~/.ssh/authorized_keys`. Test from the PC with
   `ssh box 'echo ok'`, which must work with no prompt. Add a `Host box` entry to the PC's `~/.ssh/config`.
4. Passwordless sudo for that user (`/etc/sudoers.d/claude`: `<user> ALL=(ALL) NOPASSWD: ALL`).
5. Screen Sharing on, so Remy can watch (only the System Settings switch actually enables it, not `launchctl`).
6. Install Homebrew, Bun, git, `cliclick`, Google Chrome (or Chrome Beta, see Part 4).
7. Grant **Accessibility** and **Screen Recording** to `bun` (and to `sshd-keygen-wrapper` if you want plain
   `ssh box screencapture` to work). macOS needs a human to flip these toggles. Have Claude open the right
   settings pane, then ask Remy for the click.
8. Then install Understudy (Part 4B).

### If it's Windows

1. Create a local admin account for Claude's work. Turn off "only allow Windows Hello sign-in" so a password login
   exists.
2. **Automatic login:** Sysinternals **Autologon** (stores the password encrypted). After any reboot, including
   Windows Update ones, the desktop session comes back on its own.
3. **Never sleep:**
   `powercfg /change standby-timeout-ac 0`, `powercfg /change monitor-timeout-ac 0`,
   `powercfg /change hibernate-timeout-ac 0`. Screensaver off, and no lock on wake. A locked session means no
   screenshots and no input.
4. **Headless?** Plug in an **HDMI dummy plug** (a few dollars). Without a monitor, Windows may drop to a tiny
   resolution or stop rendering properly.
5. **OpenSSH Server** (PowerShell as admin):
   ```powershell
   Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
   Start-Service sshd; Set-Service sshd -StartupType Automatic
   # Make PowerShell 7 the SSH shell (install pwsh first)
   New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Program Files\PowerShell\7\pwsh.exe" -PropertyType String -Force
   ```
   **Gotcha:** for an *admin* user, Windows ignores `~/.ssh/authorized_keys`. The key goes in
   `C:\ProgramData\ssh\administrators_authorized_keys` with locked-down permissions:
   `icacls C:\ProgramData\ssh\administrators_authorized_keys /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"`.
6. **UAC:** elevation prompts appear on the "secure desktop", which software can't click. That's deliberate, so
   no automation can approve itself. On this dedicated box only, set admin elevation to not prompt
   (`HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System`, `ConsentPromptBehaviorAdmin = 0`), and run
   the desktop agent elevated (see below). Also: a non-elevated process can't send input to an elevated window
   (UIPI), which is another reason to run the agent elevated.
7. **Windows Update:** set active hours, and turn on the "no auto-restart with logged-on users" policy so it
   doesn't reboot mid-job. Autologon covers the reboots that do happen.
8. **Watching it / remote access:** use VNC, Chrome Remote Desktop or Parsec, which show the real console session.
   **Avoid RDP:** when an RDP session disconnects, the console stays locked and GUI automation breaks (black
   screenshots, input ignored) until someone logs in at the machine. If you must use RDP, disconnect with
   `tscon <session id> /dest:console` (from an elevated prompt) instead of closing the window.
9. **Display scaling:** set it to 100%, or make every tool DPI-aware. Otherwise screenshot pixels and click
   coordinates disagree, and every click lands off-target.
10. Install Git, Bun, Node, Chrome, PowerShell 7, Tailscale (optional).

### Reaching it from elsewhere

On the home network, plain SSH to `box.local` (or its IP) works. For use from anywhere, install **Tailscale** on
both machines and SSH to the tailnet name. Never expose the browser service port to a network in plain HTTP;
tunnel it over SSH or Tailscale.

---

## Part 3: OS-level control (the "desktop session" problem)

This tripped us up more than anything else. **An SSH shell is not the logged-in desktop.**

- macOS: an SSH shell has no window server access, so GUI apps and AppleScript UI scripting don't work, and
  privacy permissions apply differently.
- Windows: `sshd` is a service, so everything it spawns runs in **Session 0**, which has no desktop. GUI apps
  you launch there are invisible, and screenshots are black.

So you need a way to run a command *inside the logged-in session* and get its output back.

**On the Mac**, Understudy ships `scripts/gui-run.sh <cmd>`. It hands the command to a LaunchAgent that lives in
the GUI session and returns the output. With that:
- Clicks and keys: `cliclick` (wrapped in `bun`, which holds the Accessibility grant).
- Screenshots: `screencapture -x a.png b.png` (one file per display). Downscale before reading
  (`sips -Z 1200`).
- `osascript` for app automation.

**On Windows**, two ways:
- *Quick:* a scheduled task with `/IT` (interactive only), triggered on demand:
  `schtasks /create /tn guirun /tr "<cmd>" /sc once /st 00:00 /it /rl highest /f` then
  `schtasks /run /tn guirun`. It's awkward for getting output back (write it to a file).
- *Better (build this):* a small **desktop agent**, a Bun script started at logon by Task Scheduler ("run only
  when user is logged on", "run with highest privileges"). It listens on `127.0.0.1` with a token and offers
  `run` (command in the desktop session, returns stdout), `screenshot` (all monitors, PNG, downscaled),
  `click x y`, `type text`, `key combo` (Win32 `SendInput`), and `windows` (list with titles and rects). Then
  expose those as MCP tools too. The browser service in Part 4 can run inside this same process.

Things that can't be automated on either OS, by design: macOS password dialogs (SecurityAgent ignores
synthetic input; use `sudo -n`, `security unlock-keychain -p`, etc.), Windows UAC secure-desktop prompts, and
privacy permission toggles. Route around them with command-line equivalents, or ask the human for that single click.

---

## Part 4: The browser (the part that matters most)

### Why not just Playwright/Puppeteer?

Claude's first instinct will be Playwright with a persistent profile. **Don't use that for the signed-in browser.**
- Google refuses sign-in to any Chrome started with `--remote-debugging-port` or automation flags ("This browser
  or app may not be secure"), and Google sign-in is the key to half the internet.
- Bot detection (Cloudflare, hCaptcha, Clerk and others) fingerprints CDP/WebDriver sessions. Suno, banks and
  ticketing sites will block you or keep challenging you.
- Recent Chrome versions block remote debugging on the default profile, and the branded build ignores
  `--load-extension`.

Playwright with its own bundled Chromium is still great for *throwaway* jobs: rendering pages, scraping public
sites, testing your own web apps. Just keep it away from the signed-in profile, and **never have scripts launch
the real Chrome app** (it fights the real one for the profile, steals the Dock/taskbar icon, and leaks
processes).

### The design that works (what Understudy does)

- **Real Chrome, started normally**, with its own `--user-data-dir`, which is a separate profile that Remy signs in
  to once. No debugging port, no automation switches. To every site it looks like a person's Chrome.
- **A companion Chrome extension** (loaded unpacked once via `chrome://extensions` → Developer mode) that talks
  to a local service over a WebSocket on 127.0.0.1. The extension handles:
  - **Seeing:** `chrome.tabs.captureVisibleTab` gives a real screenshot of the tab.
  - **Reading:** `chrome.scripting.executeScript` in the page's *isolated world* (pages can't see or tamper
    with it) returns the page text plus every visible link, button and field **with its click coordinates**.
    This `read_page` tool is what Claude should use 90% of the time, because it's far cheaper and more reliable
    than reading pixels.
  - **Scripting:** `run_js` (via `chrome.userScripts`) for the fiddly widgets.
- **Acting with real OS input**, not synthetic DOM events. Many sites ignore `element.click()` because those
  events have `isTrusted: false`. Understudy sends real keyboard and Accessibility events to Chrome's process.
  On Windows, use `SendInput` at screen coordinates. Convert from page coordinates using the window's position,
  the browser chrome height and `devicePixelRatio`.
- **Typing at human pace**, newlines as Shift+Enter, optional submit with Enter.
- **Safety checks before each action:** refuse if the URL changed since the screenshot the coordinates came from
  (`stale_observation`), or if the screen is locked.
- **Sessions with their own tabs**, so several subagents can work at once. Each passes an `agent` name on every
  call, gets its own tab, and actions are serialized through one lock.
- **Per-client API keys** with scopes (read / navigate / input / script) and optional allowed-site lists.
- **An audit log** of every action (JSONL per day). It lets you prove afterwards that, for example, nothing was
  posted to LinkedIn.
- **A password vault + `type_password`** (Part 5).
- **An MCP server** so Claude Code gets all of the above as tools. Use a small stdio relay
  (`claude mcp add … -- bun …/main.ts mcp`) rather than direct HTTP, because the relay survives service
  restarts and dropped tunnels.

Understudy's Mac-specific extras: the Chrome window lives on an invisible virtual display and input goes to the
Chrome process without moving the real cursor. That lets someone use the Mac while Claude browses. **On a
dedicated Windows box you can skip that.** Put Chrome on the real screen and let `SendInput` move the actual mouse.
Nobody else is using that machine, and it's nice to watch Claude work over VNC anyway.

### 4A. Quickest start on Windows: Claude in Chrome

Anthropic's **Claude in Chrome** extension acts in a real Chrome with real sign-ins, and Claude Code can drive it
(check the current docs for `claude --chrome` and how it connects). Run Claude Code *on the box* in that case,
since the extension talks to a local Claude Code. That's the fastest way to see the value on day one. Build the
Part 4 service when you want the vault, multi-agent tabs, audit log and access from Remy's PC.

### 4B. Mac box: install Understudy

Understudy is Xavier's private repo (`X4vier/understudy`); ask him for access. The README covers everything; in short:

```sh
git clone git@github.com:X4vier/understudy.git ~/understudy && cd ~/understudy
bun install && bun link
understudy setup                    # then grant Accessibility to the bun path it prints
understudy service install          # runs at login, auto-restarts, auto-updates from main
understudy browser setup-extension
understudy browser use-app "/Applications/Google Chrome Beta.app"   # recommended: separate app + Dock icon
understudy browser signin           # Remy signs in to his sites, then presses Enter
understudy doctor
```

Then on Remy's PC: `understudy tunnel add box <user>@box.local`, create a key on the box with
`understudy connect remy-pc`, and add the MCP relay as the README shows. The repo's `CLAUDE.md` and
`docs/` explain the internals for Claude.

### 4C. Windows box: build it

Use Part 4's design as the spec and Understudy's `docs/architecture.md`, `docs/api.md` and `docs/security.md` as
the reference, if Xavier shares them. Suggested order, with a check at each step:

1. Chrome launcher with its own profile dir; Remy signs in to Google once. **Check:** Google sign-in works
   (proves no automation fingerprint).
2. Extension + local WebSocket bridge (accept only the extension's `chrome-extension://` origin plus a shared
   secret). **Check:** screenshot and `read_page` on a test page.
3. OS input via `SendInput` with coordinate mapping. **Check:** click a button and type into a field on
   three different sites, including one React app.
4. HTTP API + API keys + audit log, then the MCP relay. **Check:** Claude Code on Remy's PC drives it through an
   SSH tunnel.
5. Sessions/tabs per `agent` name, password vault, `type_password`.
6. Run it at logon from Task Scheduler with highest privileges, plus a watchdog that restarts it.

---

## Part 5: Sign-ins, passwords and 2FA codes

- **Sessions persist** in Claude's Chrome profile, so most sites need signing in only once. Treat that profile
  like a password: the box needs full-disk encryption (FileVault / BitLocker).
- **Password vault with `type_password`:** a localhost-only page where Remy pastes a site's password. Claude then
  calls `type_password` and the service types the saved password **only if the tab is on that site over
  https**, into a focused password field. Claude never sees the password, and a phishing page or prompt
  injection can't extract it. If no password is saved, the tool returns the vault link for Claude to pass on.
  **Rule: Claude never asks for passwords in chat.**
- **Emailed codes:** a Gmail **app password** (Google Account → Security → App passwords, needs 2FA on) stored in
  the OS keychain / Windows Credential Manager, read over IMAP (`imap.gmail.com:993`, search with
  `X-GM-RAW`). That's much more reliable than clicking through Gmail's web UI. Claude checks the sender matches the
  site and enters the code only there.
- **SMS codes (Android):** pair **Google Messages for web** (messages.google.com/web) in Claude's Chrome, and
  Claude reads codes there. Some banks' codes never reach it. For those, Claude should ask Remy for the code
  *early*, before it expires.
- **CAPTCHAs:** not solved. The real-browser approach makes them rare. When one appears, a human clicks it over VNC.

---

## Part 6: Teaching Claude: the global CLAUDE.md

This is what turns the plumbing into a capability. Put it in Remy's `~/.claude/CLAUDE.md` (on Windows:
`%USERPROFILE%\.claude\CLAUDE.md`) so every session in every folder knows about it. Write it as reasoned
guidance (why, not just what), so Claude can use judgment in cases it doesn't cover. A starting template:

```markdown
## My machines

Claude Code usually runs on my PC. **box** is a <Mac mini / Windows mini PC> that is purely for Claude:
you have full control there, so do whatever's needed. `ssh box` works non-interactively.
Admin password on box: <…> (box only, never anywhere else). Prefer box for builds, long jobs,
GUI apps and all browser work.

### Browser
The `browser-box` MCP server is a real Chrome on box, signed in to my accounts. You act as me there:
anything you post, send or buy really happens under my name.
- Prefer read_page over screenshots. Subagents pass their own `agent` name on every call.
- Signing in is fine when a task needs it: type the username, then type_password. If none is saved,
  send me the vault link. Never ask for a password in chat.
- Emailed codes: Gmail over IMAP (app password in the keychain under <name>). SMS: Google Messages
  web in the browser. Bank codes: ask me early.
- Scripts must never launch the real Chrome app or use its profile; use Playwright's bundled
  Chromium for throwaway work.

### Desktop control on box
SSH shells can't see the desktop. Run GUI things through <gui-run / the desktop agent>.
Screenshots: <how>. Things only I can click: <UAC / privacy toggles>. Open the right pane, then ask me.

## Rules for acting as me
- Draft any message to a human (email, support ticket, chat) and get my OK before sending.
- Research through the browser is read-only on social sites: never post, comment, like, connect or follow.
- Before moving money, look up the provider's procedure and our past records; don't skip steps.
  Show me the payment before confirming it.
- Purchases or anything irreversible or public that I didn't clearly ask for: ask first.
- Forms and questionnaires read by systems: answer as I would if I thought it through carefully, no
  need to ask.
```

Also turn on Claude Code's **auto memory**, and tell Claude to save site-specific lessons (see Part 8) to memory
as it learns them. Each site's quirks get learned once.

**Permissions:** to let Claude really run things, use bypass-permissions mode (or a broad allowlist) for this
setup. Even then, Claude Code prompts for commands it can't fully parse, such as long heredocs or nested
`ssh '…'` quoting. Tell Claude to write scripts to files and run them rather than inlining them. A
`PermissionRequest` hook can auto-approve the rest (Xavier's approves everything except `rm`).

---

## Part 7: Useful extras (add later)

- **A long-job runner:** a wrapper that starts a job in the background, tracks progress (`done total message`
  written to a file), and lets Claude poll it with widening intervals. It also flags stalls and overruns. Without
  one, Claude either blocks for ages on a foreground command or writes `sleep` loops that leak shells. Have Claude
  state an expected time before running anything, and send anything over a minute through the runner.
- **A big external drive on the box** plus a `stash put/get` script that moves big things off the main PC
  and verifies the copy.
- **A `hosts` tool** that reports which machines are reachable and whether someone is using them.
- **Watching it work:** you may enjoy leaving Claude's Chrome window visible on the box's screen and peeking
  over VNC. Xavier does.

---

## Part 8: Lessons we learned the hard way

- **Phantom displays (Mac):** Understudy's virtual display used its process ID as the display serial, so every
  restart registered a "new monitor". After weeks there were ~1,300, and macOS's ColorSync daemon pegged the CPU,
  lagging the whole machine. Fixed now (fixed serial plus an hourly cleanup job). The general lesson: anything that
  creates OS-level devices must reuse a stable identity.
- **Keep the agent's browser off shared machines.** We first ran it on the living-room Mac connected to the TV.
  The side effects disturbed the family, so it now runs only on the dedicated box.
- **System dialogs can open where you can't see them** (e.g. on the virtual display, or off-screen). When a
  screenshot shows nothing but something is clearly waiting, capture every display.
- **Native Save dialogs** in the agent's Chrome are separate OS windows that the browser tools can't reach. Use
  OS-level clicks, or avoid downloads through the UI (see Suno below).
- **Some custom widgets ignore background clicks.** Pattern: focus the element with `run_js`, then press Enter;
  or call `.click()` from `run_js` for plain buttons; or use the link's URL directly.
- **Rich text editors** (Lexical, ProseMirror, Draft.js) ignore programmatic value setting and `execCommand`.
  Click into them and use real typing. Plain `<input>`/`<textarea>` in React apps need the native value setter
  plus an `input` event.
- **Gmail's web UI** is hard to drive. Use IMAP for reading mail.
- **Self-grading:** Claude tends to call its own work "done" and grade it generously. Ask it to compare against
  the goal and state the gaps bluntly first.

### Site notes: Suno (the example you asked about)

- Sign in once with Google in Claude's Chrome. Suno blocks automated browsers, so this only works with the
  real-browser setup.
- Lyrics box is a Lexical editor: clear the form (trash → Confirm), click the empty box, then `type_text`
  (newlines OK). The style field is a textarea: native value setter + `input` event.
- Downloads never reach disk from the agent's tab. What works: unlock the song (More options → Download →
  "Unlock & Download", which uses one of your monthly downloads). Then, from inside the page, `fetch`
  `https://studio-api-prod.suno.com/api/download/clip/<id>?format=m4a` with header
  `Authorization: Bearer <value of the __session cookie>`. It returns a signed URL; `curl` that. Space requests
  out to avoid rate limits.
- The playback stream URLs are encrypted, so don't bother with those.
- Bracketed cues within sections (e.g. `[soft, whispered]`) and style wording like "sung, melodic" improve takes
  a lot.

---

## Suggested first session

Remy, once the box exists, open Claude Code on your PC and paste:

> Read this guide (attached). We're setting up <Mac / Windows> box at <hostname>. Work through Part 2 for that
> OS, then Part 3, then Part 4 (<4B / 4A then 4C>), then write my global CLAUDE.md from Part 6. Before each
> step, say what you're about to do; when you need me to click something or sign in, tell me exactly what and
> where. Verify each layer works before moving on. Finish by having the browser generate one song on Suno
> end to end.
