Bench Remote guide
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 RemoteEarly 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
- A GitHub account. Your projects are GitHub repositories, and they run in GitHub Codespaces.
- Claude: either a Claude Pro or Max subscription, or an Anthropic API key with credit from console.anthropic.com.
- Optional: a Cloudflare account, if you want Claude to publish the websites it builds to Cloudflare Pages.
- A phone with Chrome (Android recommended). The app works in other modern browsers too, but installing APKs only works on Android.
What it costs
Bench Remote itself is free while it's in testing. You pay the services you already use, on your own accounts:
- GitHub Codespaces: personal accounts get a free monthly allowance, then usage is billed per hour of running time plus storage. Check your current allowance and spending limit at github.com/settings/billing. A codespace uses hours only while it's running. Use Standby when you're done (see When it's done).
- Claude: with a subscription, work counts against your plan's usage limits. The dollar amount Bench Remote shows after each run is what it would cost at API prices, not a charge. With an API key, you pay per use.
- Cloudflare Pages: the free plan covers typical hobby projects.
Install the app
- On your phone, open this site in Chrome.
- Tap Install on the banner at the top of Bench Remote, or use Chrome's menu → Add to Home screen / Install app.
- 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
- Tap Sign in with GitHub. The app shows a short code.
- Tap Copy code & open GitHub, paste the code, tap Continue, then Authorize.
- 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:
- Use my Claude subscription (Pro or Max). Bench Remote runs Claude Code's own sign-in on a short GitHub Actions run in your private
codeforge-hubrepository (made when you first sign in to GitHub), so you need nothing but the phone. It takes about a minute, mostly waiting for the runner. The link, the code and the finished token pass between the run and your phone encrypted, and are deleted afterwards. If Actions can't run there, Bench Remote uses one of your Linux machines, or else a codespace (a small privatecodespacecontrol-setuprepository; the first time takes a few minutes). Keep the screen open.- Tap Open Claude sign-in, sign in and tap Authorize.
- Claude shows a code. Tap its Copy button.
- Come back, paste it and tap Connect. Bench Remote tests the sign-in with a one-word prompt before saving it.
- Use an API key. Create a key at console.anthropic.com → API Keys, tap its Copy button, paste it and tap Check & save. The key is checked with Anthropic first.
3. Cloudflare (optional)
- Tap Open Cloudflare API tokens → Create Token → Create Custom Token.
- Add one permission: Account → Cloudflare Pages → Edit. Create it and tap Copy.
- 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 home screen lists your Recent repositories first, with the branch and mode you last used, then Running codespaces (these use your hours), then all your repositories with a search box.
- Start from an idea: the message box at the bottom of the home screen talks to Claude before any project exists. Describe what you want to build; Claude asks questions and proposes a plan, in the background (no codespace). When the plan is ready, its reply has a Create project button: tap it, check the name, and Bench Remote creates a private repository with the plan, brings the chat across and Claude starts building there. 💬 Planning chat on the home screen takes you back to that conversation. (Behind the scenes it lives in a private repository called
codeforge-hub, which Bench Remote creates and keeps out of your list.) - + New creates a repository: type a name (for example
todo-app), keep Private ticked unless you want it public, and tap Create. - All codespaces at the bottom lists every codespace, including stopped ones.
- More options: tap and hold a codespace (or tap its ⋯) to put it on Standby, Delete it, open its repository, or open it in the browser, without starting it first. The menu says whether the codespace has work that isn't pushed, and Delete asks before doing anything. Delete all stopped codespaces, at the bottom of All codespaces, clears them in one go (stopped codespaces don't use hours but do count towards your GitHub storage).
- Tap and hold a Recent entry (or tap its ⋯) to remove it from the list or open the repository on GitHub.
- Bench Remote reopens the last repository you used when you open the app.
The repository screen
- Pick a branch at the top. The files come straight from GitHub, so no codespace is needed to look around.
- Find files: type in Search files, or tap a filter (HTML, Images, Code, Docs…; the number is how many match). The sort menu switches between Name (folders), Largest first and Recently changed (files touched by the branch's last 10 commits come first); the last two show one flat list.
- Download: tick files, or a folder for everything in it, then Download. One file downloads as itself, several as a
.zip(up to about 100 MB). Tap Save when it's ready. Whole branch as a zip gets everything from GitHub. - Upload: ⬆ Upload picks files from your phone (up to 25 MB each), asks which folder, and commits them to the branch you're looking at in one commit. It asks first, and tells you when that branch is your main one, since that skips Merge.
- Edit: tap a text file, then Edit in the preview, to change it in the full-screen editor. Save asks for a one-line description and makes one commit to the branch you're looking at; no codespace is needed. If the file changed on GitHub while you were editing (Claude pushed, say), you choose between overwriting, reloading the newer version, or going back to your edit. + New starts a new file: type its name, with a folder if you want one.
- Rename, move, delete: tap ⋯ on a file, or tap and hold it, for Rename or move, Delete, Download, Edit and Attach. To delete several at once, tick them and tap Delete in the bar at the bottom. Each is one commit, asks first, and tells you when the branch is your main one. Earlier versions stay in the repository's history on GitHub.
- Tap a folder to open it, and a file to view it. The viewer picks its layout from the file type: Markdown shows formatted (headings, tables, pictures, links to other files), and tick boxes in task lists (
- [ ]) can be ticked; a moment later the file is saved as one commit to the branch you're looking at (on the main branch it asks once first). Code shows with colours for its language and line numbers (Wrap turns line wrapping on or off), CSV as a table, and pictures as pictures. Formatted / Source switches Markdown and CSV to their plain text. Select all selects the whole file (without the line numbers) for your phone's Copy or Share, and Copy copies it straight away. As opens a file as another type, for example a.logas Shell or a file as plain text; the choice is kept for every file with that ending, and the editor colours it the same way (auto puts it back). Google Apps Script.gsfiles open as JavaScript. - The editor shows the same syntax colours as the viewer while you type, and Enter keeps the line's indent (one step more after
{,[or(). - Tap + next to a file (or Attach in the viewer) to point Claude at it: attached files show as chips above the message box and are listed at the top of your next message. Tap a chip to remove it.
- The chip above the message box chooses where Claude runs: ☁ Background (GitHub Actions, no codespace hours; see below) or ⚡ Codespace (a live machine with streaming output and previews). In Codespace mode, Android tools adds Java and the Android SDK.
- Tell Claude what to do, as you would a developer, and tap ↑. Be specific, for example: "Build a mobile-friendly todo list PWA that works offline, then deploy it to Cloudflare Pages."
- Open session › reopens the last session for this repository without sending anything.
- ‹ goes back: from a session to its repository, and from a repository to the home 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.
- + Context (above the message box) lists all your repositories with the age of their context file. Tap Attach to include one with your next message, or type @name in the message (suggestions appear as you type).
- Build / Refresh writes or updates a repository's context file with a background run using Sonnet (a few minutes, on GitHub Actions). Build several… does a checklist of repositories, two at a time. It needs your Claude sign-in for background runs, and commits only
.codeforge/context.mdto the repository's default branch. - You can also attach files from another repository: open it, tap + next to the file, then go back to the repository you're working on. Attachments stay until you send.
- Attached context and files from other repositories are copied into your message as read-only reference; Claude can't change those repositories from here. Your message shows them as a short with: line. Messages with attachments are limited to about 60 KB.
While Claude works
- Output streams in live: Claude's messages, the commands it runs (
● Bash …) and their results. Tap long output to expand it. - Type in the box at the bottom to give follow-up instructions. Claude remembers the conversation for that project.
- The ■ button stops the current task. Nothing Claude did is lost: in a codespace or on your computer its changes stay in the folder, and in Background, where the GitHub machine is thrown away afterwards, Bench Remote keeps whatever Claude hadn't committed yet and says which files. Your next message carries on from them, put back as they were, and Claude is told which files it was in the middle of. Merge or Undo clears them.
- Model: pick a Claude model above the message box. Default uses your plan's default. Which models you can use depends on your Claude plan; if one isn't available, Claude Code says so in the output.
- Usage meters: with a Claude subscription, Session (your 5-hour window) and Weekly show how much of your plan's usage you've used and when each resets. They update after each task, and the latest figures are also shown on the home screen.
- You can leave the app or lock your phone; the work continues in the codespace and the app catches up when you come back.
- Notifications: tap Turn on on the home screen banner (or ⚙ → Notifications) to get a Bench Remote finished notification when Claude is done, even with the app closed. Use Send test to check it works.
- Claude commits and pushes its work to GitHub as it goes, so your code is safe in the repository.
- Status line: under the title, a line shows what's happening: Queued, Running, Done or Failed with a Run ↗ link for background runs, and Starting, Running, Idle or Off with Standby / Start for a codespace.
- Switch where Claude runs at any time by tapping the ☁ Background / ⚡ Codespace chip, for example to move to a codespace when you want to watch live or preview. The repository, branch and conversation stay on screen. Claude keeps short notes for each branch in
.codeforge/session.mdand reads them (plus the latest commits) after a switch, so it carries on where it left off. If Claude is in the middle of a task, Bench Remote asks before stopping it. - Each repository and branch has one conversation, whichever mode you used.
- Chat memory: Claude doesn't re-read the whole chat for every message. Each message starts it fresh with the short memory note it wrote at the end of its last reply (hidden from the chat) and your last message and its reply;
.codeforge/session.mdandplan.mdhold the rest. On long chats this uses far less of your Claude allowance. If Claude needs something from earlier, it says so and Bench Remote sends your message again with the whole chat (shown as "with: whole chat"). 📜 Whole chat above the message box does that for your next message. To have Claude re-read the whole chat every time, as before, pick Full under ⚙ → Chat memory. - Plan or Build: the 🔨 Build / 📝 Plan chip above the message box switches the repository between the two, and is remembered for it. In Plan, Claude reads and searches the whole project and talks it through with you, but the only things it can change are
plan.md(at the top of the repository) and its own notes: it keeps the plan written there and pushes it, and anything else it tries is refused automatically. When a plan reply comes back, 🔨 Build this switches to Build and asks Claude to build whatplan.mddescribes. Build is the normal mode; you can still say "don't build yet" there. Build APK always builds, whichever mode is on. Plan mode in a codespace or on your computer needs the latest Bench Remote relay; if it is older, Bench Remote says so and doesn't send the message. - Send a photo or file with a message: tap 📎 next to the message box and pick photos or files from your phone (up to 25 MB each). They show as chips above the box (tap one to remove it) and go with your next message; files on their own are fine too. Bench Remote puts them in a hidden folder on the task's branch,
.codeforge/inbox/, and tells Claude which are new, so you can say things like "fix the layout in this screenshot" or "use this as the logo". Claude copies anything the app needs to its proper place and clears the inbox when it's done. In your message they show as with: 📎 name. - No need to wait for a codespace to start: type your message and send it while it's starting or waking up. It shows as Queued above the message box (✕ cancels it) and is sent the moment the codespace is ready. One message can be queued, and it's only held while Bench Remote stays open.
- New chat (on the status line) starts a new conversation on the same branch. The code and Claude's notes stay; Claude forgets the details of the chat and picks up from its notes on your next message. Worth doing when a chat has grown long, since long chats use more of your Claude allowance per message.
Branches, merging and undo
- When you start a task from a repository's main (default) branch, Bench Remote creates a working branch for it, named after your message (for example
codeforge/add-a-footer). Claude commits and pushes there in both modes, so nothing reaches your main branch until you merge. Follow-ups and mode switches stay on the same branch, and Recent remembers it. - One open branch at a time. Until you merge it, later messages sent from main carry on in that working branch instead of starting another, so branches don't pile up (Bench Remote says Carrying on in …). To start a separate branch anyway, tick + New branch above the message box before sending; it shows only while a branch is open, and only for that message. After a merge, or if the branch was merged or deleted on GitHub, your next message starts a new one.
- After a background run, a summary card shows Claude's summary and the files it changed, with links to the changes and the run. Claude's full output is folded above it under Show log.
- Merge opens a pull request, squash-merges it into main as one commit, and deletes the working branch. If the branch can't be merged automatically, Bench Remote says so and fills in a message asking Claude to resolve the conflicts. In a codespace, Merge is under ⋯.
- The chat carries on after a merge. The conversation moves to main (below a Merged from … line if main already had a chat), and your next message there starts a new working branch from the updated main with the same chat, and Claude remembers it when the task runs in the same place (Background, the same codespace or the same computer); otherwise Claude picks up from its notes. Want a clean start? Tap New chat.
- After a merge Bench Remote asks whether to keep a read-only copy of the chat under the old branch name. Copies are listed at the bottom of the branch picker on the repository screen (📖); they open without a message box, and Delete on the status line removes one. Chats are kept on this phone unless you sync them (below).
- ☁ Sync chats (repository screen, or ⋯ on a Recent repo) keeps that repository's chats in it too, on a
codeforge-chatsbranch that is never merged into your code, so your other phone or laptop sees the same chats. It's per repository and off until you turn it on; for a public repository it warns you first, since anyone could read them. Keys and tokens are never part of a chat. Changes go up a few seconds after they happen, and a chat is brought up to date when you open it. - Long chats: with ☁ Sync chats on, the phone keeps the recent part of a long chat (at least the last 10 messages) and moves older messages to a text file on the
codeforge-chatsbranch. A 📦 line in the chat marks where they were. Claude is told where those files are and searches them when it needs something from earlier, so just ask. Without sync, the oldest parts of a very long chat are shortened to fit on the phone. - Codespace tasks get the same card when they finish (the live output stays on screen above it). ⋯ → 🏁 Finish task asks Claude to commit and push anything left, update its notes and sum up, then offers Merge and Standby together.
- If Claude ends a background run saying the rest needs a live machine, the card has Continue in Codespace, which moves the session there in one tap.
- Revert undoes a run by moving the working branch back to before it (Bench Remote asks first, and refuses if newer commits were added since). Claude is told on your next message.
- Build APK (Android projects) first asks what to build: a 🐞 Debug APK (for testing; on GitHub Actions, a codespace or one of your machines), a 🚀 Release APK or a 🏪 Play Store bundle (.aab, what Google Play takes), both signed with your own key on GitHub Actions, or ⬆ New version, then release (Claude raises versionCode and versionName first; every update needs a higher one). The first release build asks if you have a keystore: 📤 upload it (.jks, .keystore or .p12, with its password and alias) or ✨ make one on the phone, which gives you a zip with the keystore and its password. Keep that zip safe: the key goes into the repo's GitHub Actions secrets, which can't be read back, and every update of the app must be signed with the same key. 🔑 Signing key in the same menu replaces or removes it. The APK is kept on GitHub in the repo's codeforge-apk branch (the latest build of each branch), so it doesn't have to live on the phone. To install, tap Download APK on its card, open the file, and delete it from the phone afterwards. After merging, an APK built from main goes on the android-latest release page.
- Website deploys from a working branch go to a Cloudflare preview address. Merging doesn't publish anything: after a merge Bench Remote asks Deploy main to the live site?, and 🚀 Deploy on the merged card or the repo screen does it later (it warns first, since the live site changes for everyone straight away).
- With notifications on, background runs notify you themselves when they finish, even with Bench Remote closed.
When it's done
Tap ✓ Completed (or ⋯ at any time):
| Option | What it does |
|---|---|
| ⏸ Standby | Stops 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 running | Leaves 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. |
| 📁 Files | Browse 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 / :8080 | Opens the app Claude is running, if it started a server on those ports. Sign in to GitHub in your browser if asked. |
| Sort and ⬆ Upload | In 📁 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 file | In 📁 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 file | In 📁 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. |
| 🗑 Delete | Deletes the codespace. Anything not pushed to GitHub is lost; the repository stays. |
Building Android apps
- 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.)
- 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). - 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.
- 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. - Open that page and tap the
.apkto download it. Build progress and errors are on the repo's Actions tab. (Projects set up before this feature, or without theworkflowpermission, still put APKs indist/: open ⋯ → 📁 Files, tap the APK pill, tick the.apk, then Download and Save.) - 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:
.github/workflows/codeforge-android.yml(Android projects only): builds a debug APK, a signed release APK or a Play Store bundle when you tap Build APK in Bench Remote or start it from the repo's Actions tab. Pushes never start it..github/workflows/codeforge-deploy.yml: publishes a website to Cloudflare Pages when Claude pushes a commit whose message contains[deploy]. Claude writes the settings tocodeforge-deploy.json. Bench Remote also runs it when you choose to deploy after a merge or tap 🚀 Deploy.
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/.
- Windows: on the PC, open
codespacecontrol.pages.dev/setupand 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. - 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. - 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.
- In a repository, tap the mode chip and pick the machine. The first message clones the repo into
CodeForgein 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 on(Linux and macOS): kept to a repo folder. You open them from a chat's ⋯, and the operating system's sandbox (bubblewrap on Linux, built in on macOS) lets them change files in that folder and a private/tmponly. Your keys, Bench Remote's settings and your other repos are hidden, and there is no GitHub token, sogit pushdoesn't work there (Claude does that). Linux needs bubblewrap set up once: the installer offers it, or runcurl -fsSL https://codespacecontrol.pages.dev/machine/sandbox-setup.sh | sh(on Ubuntu it also adds a small AppArmor rule).codeforge terminal full: a normal shell anywhere, with everything you can do on that computer. This is the only kind on Windows, which has no such sandbox.
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
| Problem | What 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 task | GitHub 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 it | Codespaces 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 repositories | The 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 create | You may have used your free allowance or hit a spending limit. Check github.com/settings/billing. |
| No notifications | Allow 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 old | It 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" entry | That 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
- On your phone: your GitHub sign-in, your Cloudflare token (if added), preferences, and recent output from your projects. Sign out (⚙) clears it.
- In your GitHub account: your repositories and codespaces, plus encrypted Codespaces secrets for Claude, Cloudflare (if added) and the relay port (if enabled), and encrypted Actions secrets for Cloudflare in each project that uses it.
- Bench Remote's servers store nothing about you. GitHub sign-in and the Cloudflare token check pass through a small function on the Bench Remote site that forwards the request and keeps nothing.
What Claude can do
- Claude Code runs without asking permission for each step inside your codespace. It can run any command, install software, change files, and commit and push to that repository. That's what makes it work from a phone.
- Content Claude reads, such as web pages, packages or issue text, could try to trick it into doing something you didn't ask. Keep an eye on what it does and review its commits.
- Every Codespaces secret available to a codespace can be read by programs running in it, including Claude. That includes the relay-port sign-in, which has access to your repositories and codespaces. If you don't want that, untick Open the relay port automatically and set port 5555 to Public yourself when needed (see Troubleshooting).
- Each codespace's connection (port 5555) is reachable from the internet, but it only accepts requests that carry your GitHub sign-in, and only from the Bench Remote site.
Remove everything
- In Bench Remote: ⚙ → Sign out.
- Revoke GitHub access: github.com/settings/applications → Authorized OAuth Apps → Bench Remote → Revoke.
- Delete the saved sign-ins: github.com/settings/codespaces → Codespaces secrets → delete
CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY,CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_IDandCODESPACECONTROL_GH_TOKEN. - Delete codespaces you no longer need at github.com/codespaces, and repositories (including
codespacecontrol-setup) if you want. - 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.