Bench Remote guide

Version 2026.11.10 (dcced55)

Bench Remote lets you use Claude Code from your phone. Each project gets its own GitHub Codespace, a full Linux computer in the cloud where Claude writes, runs and commits code while you watch the output live. Everything runs on your own GitHub, Claude and Cloudflare accounts.

Open Bench Remote

Early test version. Things may change or break. If something goes wrong, tell the person who shared Bench Remote with you and include what the app showed.

What you need

What it costs

Bench Remote itself is free while it's in testing. You pay the services you already use, on your own accounts:

Install the app

  1. On your phone, open this site in Chrome.
  2. Tap Install on the banner at the top of Bench Remote, or use Chrome's menu → Add to Home screen / Install app.
  3. Open Bench Remote from your home screen from now on.

Sign in (3 steps)

The first time you open Bench Remote it shows three steps. Each one is checked before it's saved. Your Claude and Cloudflare sign-ins are saved as encrypted Codespaces secrets in your GitHub account, so your codespaces can use them. Nothing is stored on Bench Remote's servers.

1. GitHub

  1. Tap Sign in with GitHub. The app shows a short code.
  2. Tap Copy code & open GitHub, paste the code, tap Continue, then Authorize.
  3. Switch back to Bench Remote. It updates by itself within a few seconds.

Bench Remote asks for access to your repositories and codespaces so it can create them for you. The Open the relay port automatically box (on by default) lets your codespaces make themselves reachable from your phone. See Privacy and security for what that means before you decide.

2. Claude

Pick one:

3. Cloudflare (optional)

  1. Tap Open Cloudflare API tokens → Create Token → Create Custom Token.
  2. Add one permission: Account → Cloudflare Pages → Edit. Create it and tap Copy.
  3. Paste it into Bench Remote, add your Account ID (the long code in your Cloudflare dashboard's address bar), and tap Check & save.

Or tap Skip for now; you can add it later under ⚙ → Sign-in & accounts.

You only do this once. On another phone, just sign in with GitHub and your saved Claude and Cloudflare sign-ins are picked up.

Start a project

Pick a repository

The repository screen

On first use Bench Remote adds one commit to the chosen branch: a folder called .devcontainer/codespace-control/ that sets up the codespace, plus its GitHub Actions workflows. Your own files and any existing devcontainer are left alone.

The progress bar shows each stage. A brand-new codespace takes about 3–6 minutes the first time (longer with Android tools) while it installs Claude Code. Starting it again later takes under a minute.

Context from other repos

When one app needs to work with another (for example a meal planner sending a shopping list to a list app), Claude needs to know how the other app works. Each repository can have a short .codeforge/context.md: what the app is, how other apps can talk to it (links, share formats), the exact data it expects, and where that's implemented. Claude keeps it up to date when it changes those things.

While Claude works

Branches, merging and undo

When it's done

Tap ✓ Completed (or ⋯ at any time):

OptionWhat it does
⏸ StandbyStops the codespace. Files are kept and it stops using hours. Tap Start on the home screen to continue later. A progress bar shows the shutdown, and Codespace is off appears when it has finished.
▶ Keep runningLeaves it on for more prompts or to preview the app. It goes on standby by itself once Claude has finished and you've stopped using it for a while (⚙ → Standby after; never in the middle of a task). If it's asleep when you send a message, Bench Remote wakes it up first.
📁 FilesBrowse the project as folders, including work Claude hasn't pushed yet. Search, or tap a filter pill (APK, HTML, Debug, Release…; swipe for more). Tick files or whole folders; the bar at the bottom shows what's selected. One file downloads as itself, several as a .zip. Tap Download, then Save.
Preview :3000 / :8080Opens the app Claude is running, if it started a server on those ports. Sign in to GitHub in your browser if asked.
Sort and ⬆ UploadIn 📁 Files, the sort menu offers Name (folders), Largest first and Recently changed. ⬆ Upload copies files from your phone into the codespace (up to 25 MB each); they aren't committed until Claude, or you, commit them. Needs a codespace started after this feature was added.
👁 View a fileIn 📁 Files, tap 👁 next to a text or code file to open it in the viewer (formatted Markdown with tick boxes, colours for code; ticks are saved in the folder, not committed). Next to an image, 👁 shows it in a popup, with its size in pixels. Use ‹ Prev / Next › or swipe to flip through the images shown (tap the Images pill to see only images).
✎ Edit a fileIn 📁 Files, tap ✎ next to a text file (HTML, CSS, JavaScript, JSON, Markdown and similar) to edit it full screen, with line numbers and the current line and column shown at the top, then Save. If Claude changed the file while you were editing, Bench Remote asks before overwriting. Saved edits aren't committed until Claude's next commit, or ask Claude to commit them.
🗑 DeleteDeletes the codespace. Anything not pushed to GitHub is lost; the repository stays.

Building Android apps

  1. For a codespace, switch the chip to ⚡ Codespace and turn on Android tools before sending. The codespace then comes with Java and the Android SDK installed. The first start takes a few extra minutes. (Background runs don't need this.)
  2. An APK is only built when you tap Build APK on the card at the end of a run. Claude never starts a build itself, so you can go through as many fixes as you like without one. Build APK asks where: ☁ GitHub Actions (free minutes, nothing to install), ⚡ This codespace (with Android tools), or one of your machines that is online (Claude installs Java and the Android SDK there if needed, builds, and puts the APK in dist/; the card then has Get the APK; choosing another machine moves the chat there).
  3. Auto-fix (on unless you turn it off in that menu): if a GitHub Actions build fails, the error goes to Claude, who fixes and pushes, and the app builds again by itself when Claude is done, at most 3 builds; then it stops and shows the last error. On a machine or codespace Claude fixes errors as it goes, with the same limit. With auto-fix off a failed build is only reported.
  4. On GitHub Actions a debug APK takes a few minutes, without using codespace hours. The chat shows the build and, when it's done, a Download APK link. A build of your main branch is published on the repo's android-latest release page: github.com/<you>/<repo>/releases/tag/android-latest. A build of a working branch is under that run's Artifacts on the Actions tab; merge first if you want it on the release page.
  5. Open that page and tap the .apk to download it. Build progress and errors are on the repo's Actions tab. (Projects set up before this feature, or without the workflow permission, still put APKs in dist/: open ⋯ → 📁 Files, tap the APK pill, tick the .apk, then Download and Save.)
  6. Open the downloaded file to install it. Android may ask you to allow installs from Chrome or your Files app the first time (Settings → Apps → Special app access → Install unknown apps).

The first Android build in a new codespace is slow (often 5–15 minutes). Later builds are much faster.

Builds and deploys on GitHub Actions

Codespace time is metered, so Bench Remote adds two GitHub Actions workflows to each project, which run on GitHub's own free build minutes instead:

Background mode (prototype)

With the chip on ☁ Background, no codespace is used at all: Claude runs your prompt on a GitHub Actions machine, commits and pushes, and Bench Remote shows the whole transcript when it finishes (progress shows which step it's on meanwhile). Reply in the box at the bottom to continue the same conversation. There's no live output, no previews and no 📁 Files; if Claude decides something needs a codespace it says so at the end. Background runs need your Claude API key, or a subscription token from claude setup-token run on a computer, pasted once on this phone (Bench Remote asks for it the first time you send). Each run's transcript is saved in the repo's codeforge-sessions branch, so on a public repo anyone can read it.

Adding workflow files needs the workflow permission on your GitHub sign-in. If you signed in before this feature, open ⚙ → Sign-in & accounts, tap Sign in again under GitHub and approve the new permission. Don't sign out for this: signing out clears the chats saved on the phone. Your machines pick up the new sign-in before their next task (agent 0.9.0 or newer: ⋯ → ⬆ Update on older ones), so Claude can push workflow files from them too. For deploys, Bench Remote copies your Cloudflare token into the repo's Actions secrets. If Cloudflare was connected on another phone, enter the token again under ⚙ → Sign-in & accounts → Cloudflare → Change.

My machine: your own laptop or PC

Claude can also work on your own computer (Windows, Linux or macOS): free, nothing to start up, and builds run right there, so for an Android app Claude builds the APK itself, fixes any errors and builds again until it works. The APK ends up in the repo folder's dist/.

  1. Windows: on the PC, open codespacecontrol.pages.dev/setup and run Bench Remote Setup (if Windows says it protected your PC: More info → Run anyway). It checks for Node.js, Git and Claude Code and asks before installing anything missing. Linux or macOS: open ⚙ → 💻 My machines → + Add a machine and paste the line shown there into a terminal.
  2. The computer shows a QR code and a code like ABCD-2345. Scan the QR code with your phone's camera, or tap 📷 Scan QR code or type the code in Add a machine, and tap Add this machine. Your phone sends its GitHub sign-in to that computer, encrypted so only it can read it.
  3. On Windows, the setup then opens the Claude sign-in if Claude Code isn't signed in yet, sets the agent to start with Windows and says when it's done.
  4. In a repository, tap the mode chip and pick the machine. The first message clones the repo into CodeForge in your home folder; after that it works like a codespace.

The computer needs to be on and connected; if it isn't, Bench Remote says so and Retry tries again. As with a codespace, ⋯ has 📁 Files (browse, preview, edit and download the folder, including work that isn't pushed, like a built APK), Finish task and Merge. When you're done with the project, ⋯ → 🗑 Delete folder (or Clean up on the status line) deletes the repo folder on the computer; it refuses, and shows what, if anything isn't pushed yet. My machines shows each computer's folders and storage: the limit (10 GB to start, change it per machine) only counts repo folders, not tools like the Android SDK. You can pair several computers and pick one per repository. Anything Claude does runs as you on that computer, inside the repo folder. When a computer reaches 80% of its limit, the next chat you open there says so once, with its biggest folders.

Sleep, on and off. While Claude works, the computer is kept from going to sleep by itself (agent 0.11.0 or newer: ⋯ → ⬆ Update on older ones); between tasks it sleeps as usual. Your phone can sleep too: when you come back the app picks up the run, even one that finished meanwhile (agent 0.11.1 or newer). Closing a laptop's lid or choosing Sleep still sleeps it. In the mode chip's list, ⏻ Shut down sits next to each computer that is on. For an Amazon EC2 server that is off it says ⏻ Start (the first time it asks for an AWS key that can only start and stop that server), and opening a repo on such a server starts it by itself, then carries on once it is online. ⚙ → 💻 My machines → ⋯ → ⏲ Shut down when idle turns an EC2 server off after a time you choose with no task running and nothing sent from the phone, so it stops costing.

Your own copy. Claude edits in its working folder (CodeForge/<owner>/<repo>). After the first run that finishes, the computer also keeps your own copy of the project (shown under 📁 Repo folders and storage, in Bench Remote/.codeforge/<owner>/<repo>/live). It only changes when a run finishes, and then it gets Claude's committed work in one go, so an app you run from it never sees half-done edits. Ask Claude to start the app "for me" and it starts it from there. If you change files in your copy yourself, it is left alone and the chat says so. Stop keeps Claude's unfinished edits in the working folder, and the next message tells Claude which files they are. 🗑 Delete folder removes both, and warns about changes in either.

🛠 Actions: tests, builds and the app with one tap

On the repo screen of a repository that runs on one of your computers (the mode chip shows 💻), tap 🛠 Actions next to the sort menu; in its chat it is under ⋯ → 🛠 Actions. It shows what that repository can do, found in its files: Run tests, Build, lint and type checks (from package.json), Gradle tests and a debug APK, pytest, cargo, go and make targets, and Install dependencies. Tap one and its output appears as it runs; ■ Stop ends it. When something fails, Ask Claude to fix this sends the end of the output to the chat. Tests and builds run in Claude's working folder, one at a time, and wait while Claude is working there.

Run the app starts the repo's dev (or start) script from your own copy, installing its dependencies the first time, and shows the port it is on. It keeps running until you tap ■ Stop (or ↻ Restart). Git lists the files with unfinished edits; tap one to see what changed. ⬇ Pull brings in new commits from GitHub, Recent commits lists the last few, and Discard edits puts the working folder back to its last commit, after asking.

Running lists what is running from the repo's folders (a server Claude started, the app) with its ports and a ■ Stop; Claude's own run is never listed, so it can't be stopped from here by mistake. Logs shows the end of this repo's relay log or the Bench Remote agent's, with tokens hidden. Your buttons: ask Claude for one ("add a button that deploys to staging") and it adds it to .codeforge/actions.json in the repo; it then shows under 🛠 Actions. Needs agent 0.10.0 or newer (⋯ → ⬆ Update).

Terminal on your computer

The terminal is hidden until you turn on ⚙ → Developer options; 🛠 Actions covers the usual things. ⚙ → 💻 My machines → ⋯ → ⌨ Terminal opens a shell on that computer, full screen, in your home folder; in a chat that runs on a computer, ⋯ → ⌨ Terminal opens one in that repository's folder. Tap the terminal for the keyboard; the row underneath adds Esc, Tab, Ctrl (then a key, for Ctrl+that key), ^C, the arrow keys and Paste, and A− / A+ change the text size. On Linux and macOS it is a full terminal, so programs like nano, htop or claude work; on Windows it is PowerShell without a full terminal: type a command in the box and tap Send. ✕ leaves it running on the computer (for 30 minutes while nobody looks), and opening it again carries on where you were; End closes the shell. Up to 3 at a time per computer.

Terminals are off until you allow them on the computer itself; the phone can't turn them on. There are two levels:

codeforge terminal off turns them off again and closes any that are open the next time the phone uses them. Bear in mind that Claude itself runs on the computer with your permissions, so anyone who can send it messages can already ask it to do a lot.

⬆ Update Bench Remote on it (same menu) fetches the latest agent and restarts it in a few seconds; it asks first if Claude is working there. Computers with an agent older than 0.7.0 need the installer run on them once more instead.

Developer tools (Linux machines)

On a Linux machine, ⚙ → 💻 My machines → ⋯ → 🧰 Developer tools installs Java 21, the Android SDK, Python, the GitHub CLI (gh), Go, Rust, Bun and Flutter once, in Bench Remote's own folder on it (~/.local/share/codeforge/tools, no admin password). Bench Remote offers this right after you add a Linux machine, with Java, Android, Python and gh ticked. Claude then uses them straight away instead of spending part of a task (and your credits) installing them. When Claude needs one that isn't there, it asks Bench Remote to install it; small ones go straight in, and big ones (Android SDK, Flutter) wait until you tap Install on the phone. Remove deletes a tool again, after a warning.

Anything else Claude needs from the system's own packages (say the libraries a browser needs) is never installed without you. Claude asks, and the phone shows Claude wants to install system-wide with the package names, Claude's reason and the exact admin command (for example sudo apt-get install -y libgbm1). Tap Allow to run it or Deny to refuse; Claude waits for your answer. Requests you haven't answered also wait under ⋯ → 🧰 Developer tools. This needs apt-get or dnf, and sudo without a password on that machine (cloud machines usually have it). Where sudo asks for a password, Claude tells you the command to run yourself instead.

Limits: Linux only (x64 or arm64) for now. On Windows and macOS this menu isn't shown, and Claude says what's missing so you can install it. Check the disk has room first: the Android SDK needs about 1.5 GB free while it installs, plus space for Gradle's downloads. A small cloud server (an 8 GB EC2 disk, say) may need a bigger disk.

Script library

When Claude writes something other projects could use (a build or deploy script, a helper, a fix for a tricky error, a recipe of steps that worked), Bench Remote saves it to your private codeforge-library repository on GitHub. In later projects Claude checks the library first and reuses what fits, instead of writing it again. Short entries are saved by themselves and the result card says 📚 Saved to the library. For long ones (over 150 lines) the card asks first. ⚙ → 📚 Script library lists the entries; tick some and tap Delete to remove them. Projects that already use them keep their own copy, and GitHub keeps the library's history.

Claude reads the library when it works on your own machine or in a codespace. Background runs on GitHub Actions can't open it, so Bench Remote sends the library's index with each message there; if an entry would help, Claude names it and you attach it with + Context on your next message.

Troubleshooting

ProblemWhat to do
Stuck on "Waiting for the relay"A first start can take 6 minutes, or more with Android tools. If it's much longer, make sure Open the relay port automatically is on (⚙ → Sign-in & accounts → GitHub). Or open ⋯ → Open in VS Code (web), go to the Ports tab, right-click port 5555 → Port Visibility → Public.
"Invalid API key" or "Invalid bearer token"Your Claude sign-in is wrong or expired. Redo step 2 under ⚙ → Sign-in & accounts → Claude → Change, then restart the codespace (Standby, then Start) so it picks up the new sign-in.
Codespace stopped in the middle of a taskGitHub stops codespaces it thinks are idle, and it doesn't count Claude working. Codespaces created by the current version avoid this when Open the relay port automatically is on: Bench Remote handles standby itself. Older codespaces keep GitHub's timer; delete and relaunch them. Send a message to wake a sleeping codespace; Claude keeps the conversation.
A setting changed but the codespace doesn't see itCodespaces read your sign-ins when they start. Use Standby, then Start.
"GitHub sign-in is not available"The Bench Remote site isn't fully configured. Tell the person who shared it. Meanwhile you can use a GitHub personal access token (classic, with repo, codespace and workflow scopes) under ⚙ → Advanced.
Can't see or use an organisation's repositoriesThe organisation may block third-party apps. Ask an owner to approve Bench Remote in the organisation's settings (Third-party access), or use a personal access token.
Codespace won't createYou may have used your free allowance or hit a spending limit. Check github.com/settings/billing.
No notificationsAllow notifications for this site in Chrome, turn them on in ⚙ → Notifications, and tap Send test. Codespaces created before you turned notifications on won't notify; open them again or create a new one.
Files says the codespace is too oldIt was created before downloads existed. Delete the codespace and open the repo again, or use the last pushed version from GitHub link.
A "Not a Bench Remote codespace" entryThat codespace was created outside Bench Remote, so there's nothing to connect to. Tap Set up to open that repo with Bench Remote instead.

Privacy and security

Where your data lives

What Claude can do

Remove everything

  1. In Bench Remote: ⚙ → Sign out.
  2. Revoke GitHub access: github.com/settings/applications → Authorized OAuth Apps → Bench Remote → Revoke.
  3. Delete the saved sign-ins: github.com/settings/codespaces → Codespaces secrets → delete CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and CODESPACECONTROL_GH_TOKEN.
  4. Delete codespaces you no longer need at github.com/codespaces, and repositories (including codespacecontrol-setup) if you want.
  5. If you used an API key or a Cloudflare token only for Bench Remote, delete them in the Anthropic console and Cloudflare dashboard as well.