A project normally runs on your computer. You can move one to the cloud. The agent, its commands and the preview then run there, and keep running when your computer sleeps. You can move it back at any time.
A project lives in one place at a time: This computer or Cloud. The button in the project header shows which.
What you need
- A place to run it. Graspable does not provide one. You use your own E2B account or your own server.
- The Graspable agent with an API key. See below.
Set up a cloud
Open Settings → Cloud.
E2B sandbox. Enter your E2B API key and choose Save. Get a key opens E2B's key page. The Domain field is only for E2B running in your own cloud.
Your E2B account must hold an agent image for your exact Graspable version. Someone has to build it once per version. See the section for developers and admins below.
Your own server. Enter the Agent address and the Agent token that your admin gives you, and choose Save.
These details are stored in your computer's keychain.
Move a project to the cloud
- Open the project. Wait for any run to finish.
- Click This computer in the header.
- Choose Move to E2B sandbox or Move to Your own server.
The project's files, run history and memory travel with it. Only when the cloud has everything is the copy on your computer removed. The header then reads Cloud.
Work on a cloud project
It works like a local project: the editor, runs, approvals, memory and the preview. An E2B sandbox pauses itself after 30 minutes without contact and wakes when you use the project again. A run that has started gets up to an hour to finish, even if you close the app. From the header button you can also choose Pause now (stops the cost; files are kept) or Wake now.
Move it back
Click the Cloud button and choose Move back to this computer. The project is copied back and then removed from the cloud. With E2B, the sandbox is deleted.
You cannot move a project while a run is going.
What does not work in the cloud
| Not available | Why |
|---|---|
| A ChatGPT or Claude subscription sign-in | A subscription sign-in stays on your computer |
| Claude Code and the Codex CLI | They use the sign-in on your computer |
| A model on your computer or local network | A cloud agent cannot reach it |
| Headset preview | Not available for cloud projects yet. Move the project back first |
So a cloud run needs the Graspable agent with an API key account. If you try something else, the run is refused with an explanation. Your API key is sent with each run and is not stored in the cloud.
Costs
Graspable adds no charge for cloud agents. Your provider bills you: E2B for the time the sandbox runs, or whatever your server costs. Your model provider bills the API key as usual.
The backup
When you move a project up, the copy that was sent is kept on your computer in ~/Graspable/projects/.cloud. If the sandbox is lost, the header button shows "not found" and offers Restore the copy from before the move. Work done in the cloud after the move is not in that copy.
The backup is removed after the project has moved back.
For developers and admins
These steps need a terminal.
Build the E2B image
The app asks E2B for an image named after its version, for example graspable-agent-0-9-16. Build it from a checkout of the Graspable source at that version. You need Bun 1.4 or newer.
E2B_API_KEY=your-key node scripts/sandbox/build-e2b-template.mjs
Repeat this for every new app version. Without it, moving a project fails with "No cloud image for Graspable …".
Run your own agent server
The cloud agent is the same agent program the desktop app runs, started in remote mode. Build it for Linux from the source (the image script above shows the build command). The server also needs Node.js and, for the browser checks, Chromium.
GRASPABLE_REMOTE=1 GRASPABLE_SIDECAR_TOKEN=a-secret-of-32-or-more-characters ./graspable-agent --port 4747
- The token must be at least 32 characters. The agent refuses to start in remote mode without one.
- Port 4747 is the agent. The next port, 4748, is the gateway to the project's preview. Both require the token.
- The Agent address in Settings must start with
https://, so put TLS in front of both ports. - The agent must be the same Graspable version as the app. Update both together.