Sandboxes
Cloud Sandboxes on Vercel
A Cloud Sandbox is a persistent machine in the cloud that runs your agents — no Mac required. You create it once, clone repositories onto it, and it stays yours: your code and installed dependencies are saved between sessions, it sleeps when you're not using it, and it turns back on in seconds when you are.
Think of it as a dedicated machine that lives in the cloud instead of on your desk. It shows up in your list of machines right next to any Macs you've paired, and you work against it exactly the same way.
When to use a Cloud Sandbox#
| Paired Mac | Cloud Sandbox (Vercel) | |
|---|---|---|
| Where it runs | Your own Mac | A persistent cloud machine |
| Needs your computer | Yes — your Mac must be on | No — runs entirely in the cloud |
| Your repos | Your real filesystem | Cloned onto the sandbox, saved between sessions |
| Always reachable | Only when your Mac is awake | Wakes on demand, anytime |
| Best for | Working on your actual local projects | Working from anywhere, without your Mac nearby |
A Cloud Sandbox is the right choice when you want a stable place for agents to work that's always available — from your phone, on the go, or when your Mac is asleep.
A Cloud Sandbox you create here is persistent and reusable — different from the temporary sandbox that spins up just for a single task when you open a GitHub repo. This one you add once, clone repos onto, and come back to, with everything saved between sessions.
Before you start#
Cloud Sandboxes run on Vercel, using your own Vercel account, so usage is billed to your Vercel plan.
RepoGo has two Vercel integrations. They are separate and their keys are not interchangeable:
| Integration | What it does | Credentials it asks for |
|---|---|---|
| Vercel AI Gateway | Gives the RepoGo agent access to AI models | An AI Gateway API key |
| Vercel under Sandbox Providers | Lets RepoGo create and manage cloud sandboxes in your Vercel account | A Vercel account access token, team ID, and project ID |
To create a sandbox:
- Open the left drawer, tap your profile icon, and choose Integrations.
- Under Sandbox Providers, open Vercel.
- Use the link shown there to create a Vercel account access token, then enter the token as API Key.
- Copy your Team ID from Vercel's team settings and your Project ID from the selected project's settings.
- Tap Connect.
Once Vercel is connected, you can create as many Cloud Sandboxes as you need.
An AI Gateway key will not work in the Sandbox Providers form. Likewise, a Vercel account access token does not supply model access to the RepoGo agent.
Create a Cloud Sandbox#
- Open your list of machines and tap ＋ Add Server.
- Choose Vercel.
- Tap Create Sandbox.
RepoGo provisions the sandbox, starts it, and waits for it to come online. Within a few seconds it appears in your list as online and ready to use.
From there it behaves like any other machine: open a project on it, clone a repo, and start a chat.
Your work is saved#
A Cloud Sandbox is persistent. Everything on its disk — the repositories you clone, your installed dependencies, your configuration — is saved automatically and restored every time the sandbox wakes. You can come back days later and pick up exactly where you left off.
Because the sandbox keeps your repos, you only clone and install once. Future sessions skip that setup entirely.
Turning on and off#
You don't manually manage the machine — RepoGo handles it for you:
- It sleeps when idle. After a period without activity, the sandbox pauses itself. While it's asleep, no compute is running.
- It wakes when you need it. Open a workspace or start a chat on the sandbox and it turns back on automatically — typically in just a few seconds. You can also turn it on yourself from the sandbox's screen.
- Your data is untouched across sleep and wake. Sleeping only pauses the compute; your files stay exactly as you left them.
This is the core idea: a Cloud Sandbox is a machine that's there when you want it and quietly out of the way when you don't.
How long a session runs#
When a sandbox is awake, it runs as an active session. Sessions can run for an extended stretch of work (up to several hours) before the sandbox pauses itself. When that happens, the sandbox simply goes to sleep — and the next thing you do wakes it again. You'll rarely notice the transition.
Keeping your sandbox updated#
Your Cloud Sandbox runs RepoGo's host software, and we ship improvements to it regularly. RepoGo keeps your sandbox current so you always get the latest fixes and features:
- The sandbox's screen shows its current version and tells you when an update is available.
- Updating takes a few seconds — the sandbox applies the new version and restarts. Your repos and data are unaffected.
Costs and limits#
- Cloud Sandboxes run on your Vercel account, so compute and storage usage count toward your Vercel plan.
- You're billed for compute only while a sandbox is awake — a sleeping sandbox isn't running, so it doesn't consume compute.
- A small amount of storage is used to keep your sandbox's saved state (your repos and dependencies) while it's asleep, so it can resume instantly.
- To stop all usage for a sandbox, remove it (see below), which deletes it and its saved state.
Structuring your sandboxes#
A Cloud Sandbox can hold one repository or many, so how you split your work across sandboxes is up to you. Two guidelines keep it manageable:
Recommended: one sandbox per project. Scoping a sandbox to a single project (or a single client) keeps everything tidy — its dependencies, its running services, its environment.json, and its usage all belong to one thing. When you're done with a project you remove its sandbox and nothing else is affected. This is the simplest mental model and the one we recommend by default.
You can also run multiple projects on one sandbox. Nothing stops you from cloning several repositories into the same sandbox and running them side by side. Normally the catch would be port collisions — two apps both wanting 3000. With portless that goes away: each service claims a friendly hostname like web.localhost or api.localhost instead of fighting over a port, so any number of apps can run together without conflict.
The trade-off is just manageability, not capability:
- Per-project sandboxes — clean separation, independent sleep/wake and usage, easy to remove one without touching the others. Best when projects are unrelated.
- One shared sandbox — fewer machines to keep track of, everything in one place, and with portless no port juggling. Best for a set of services that belong together (e.g. a frontend + API + worker for the same product).
A good rule of thumb: group things that ship together, separate things that don't. Structure your sandboxes the way that's easiest for you to reason about — RepoGo handles the rest.
Managing your sandboxes#
From a sandbox's screen you can:
- Rename it so it's easy to recognize in your list.
- Turn it on if it's asleep.
- Update it when a new version is available.
- Remove it when you no longer need it. Removing a Cloud Sandbox deletes it and everything saved on it, and stops any associated usage.
Frequently asked questions#
Do I need a Mac to use a Cloud Sandbox? No. A Cloud Sandbox runs entirely in the cloud. You can create and use one with just the iPhone app and a connected Vercel account.
Why does RepoGo say my Vercel key is invalid? First check which Vercel integration you opened. Vercel AI Gateway accepts an AI Gateway API key. Vercel under Sandbox Providers requires a Vercel account access token plus the team and project IDs. A key from one form cannot be used in the other.
Why is Codex connected but missing from my chat? The chat must use a project on the cloud sandbox, not a project stored on the iPhone. Connect Codex under Integrations, create or wake the sandbox, then open or clone the project on that sandbox. See Connect Your Coding Agents.
Will I lose my work when the sandbox sleeps? No. Sleeping only pauses the compute. Your repositories, dependencies, and files are saved and restored when it wakes.
How fast does it wake up? Usually just a few seconds — fast enough that opening a workspace on a sleeping sandbox feels immediate.
Can I have more than one? Yes. Create as many Cloud Sandboxes as you like — for different projects, clients, or environments. See Structuring your sandboxes for how to split your work.
Should I put all my projects in one sandbox or use one each? We recommend one sandbox per project for the cleanest separation, but you can run several projects in one — and with portless they won't fight over ports. See Structuring your sandboxes.
What happens to my data if I remove a sandbox? Removing a sandbox permanently deletes it and everything saved on it. If you want to keep your changes, push them to GitHub first.
Next steps#
- New to RepoGo? Start with Getting Started.
- Want to drive everything hands-free? See the Voice Agent.