FAQ for engineers

Before you hand work to an AI, find out how ParallelSandbox works, where your code and data go, and what stays behind. This page is for people; the AI reads SKILL.md and the tool reference.

ParallelSandbox is operated by your AI: starting boxes, setting things up and deleting them are things you ask your AI for in a sentence, and it calls the matching tool or REST endpoint. The sandbox_* tools and /v1/... endpoints below are there so you know what it actually does.

What can ParallelSandbox do for me?

• Your AI (Claude Code, Codex, Cursor, Gemini CLI, or any client that speaks MCP) opens a box for each piece of work: a small remote Linux virtual machine with Docker, git, Node, Go, Chromium and a virtual display.
• In the box the AI runs the services you changed, tests them in a real browser or an Android or iPhone simulator, takes screenshots and recordings, and hands the result to you to try in the app ("Ready for you"). You circle what is wrong and say what you see; your feedback goes back to the same conversation.
• One box per piece of work, isolated from each other. Several can run at once without fighting over ports, databases or your own machine.
• There is no AI inside the box. Your own AI does the work through MCP tools; ParallelSandbox itself never sends your code to an AI model.

What is a box like?

An x86_64 Linux machine (Debian 12). Each size unit is 2 vCPU, 8 GB of memory and 40 GB of disk, and a box is 1, 2, 4 or 8 units. Docker, git, Node, Go, Python, PHP, Chromium and a virtual display are built in; Java, Android, .NET, Rust and Flutter toolchains are added when needed.

Where do I start?

1. See the real flow first: the example repos are two public repos that run locally with docker compose up, and the page lists every step of running them in a box.
2. Connect: paste the line from the quick start into your AI. It installs the skill and signs in to your account with OAuth; you do not hand it any key.
3. Make the first task small, for example "run this repo in a box, test the home page in a browser, and hand it to me for review".

What does the architecture look like?

How does one piece of work run, start to finish?

1. Start: the AI calls sandbox_start with what the box is for, the services it runs and the ports they listen on, the secrets to bring and the environment to plug into. The box starts from a clean snapshot that holds no account data.
2. Code in: the AI runs git clone in the box, or sends your local working tree into the box through the ParallelSandbox API with sandbox_sync.
3. Run and test: the AI builds, starts services and runs tests with sandbox_exec, and takes screenshots and recordings with sandbox_shot.
4. Hand over: the AI hands the box to you with sandbox_review. It shows up under "Ready for you" in the app; you open the page or the simulator, use it, and circle anything wrong.
5. Stop: once you are done, the AI calls sandbox_stop (or you tap "Shut down" in the app) and the box's disk is deleted with it. Commit, push or pull back anything you want to keep before that.

How long does a box stay?

• 10 minutes without activity → frozen: no credits are charged, memory and /work are kept, and the next call wakes it in a few seconds.
• 24 hours after its last use → stopped for good, disk deleted. To keep it longer, tell your AI "keep this box for 3 days"; it sets that when it starts the box, up to 7 days.
• Once stopped, the box's URLs stop working and /work does not come back; a new box has new URLs.

My frontend and backend live in several repos. How does a box run them?

Can one box run several repos?

Yes. A box is a Linux machine: the AI can clone several repos under /work and run them together with docker compose or their own commands. Services find each other by name (for example api:3000), just like compose on your machine.

Or one box per service?

That works too. With services in different boxes, a link points a name in box B at a port in box A: the programs in B call the host name they always use, with no config change. It fits two people (or two AI conversations) each changing one service and testing them together.

Can boxes opened by two different people be linked?

Yes, as long as they are in the same account: a team shares one ParallelSandbox account (see team setup), which holds the boxes, environments, secrets, published versions and credits. Links only connect boxes of the same account. An account has no members or roles for now.

What about the services I did not change?

It depends on where they run:

Your AI sets environments up over REST; there is no screen for it. All you do is run the connector in your own network (one docker run line). New addresses or settings on an environment reach only boxes started afterwards.

And services I do not own (another team, a third party)?

If your network reaches it, a box can too: run a connector where it is reachable and list its host:port. External services that only accept known IPs are listed the same way, and the traffic leaves from your own network with your public IP. A service you cannot reach yourself, a box cannot reach either.

Can a service on my dev call the copy I changed in the box?

Not over your private network: the connector only lets boxes connect out, and nothing on your network can connect into a box through it; a service on your dev that calls an internal host name keeps calling the copy on your dev.

The box's public URL (https://<id>-<key>.box.parallelsandbox.com), on the other hand, is reachable by anything on the internet, so callbacks such as webhooks can point at it.

To test "caller → changed service", the simplest way is to put the caller in the same box too, or in another box linked to it.

My code and data

Will the box always have my whole repo?

Not necessarily. It depends on how the AI puts it there:

• git clone: the box fetches it itself. A private repo needs a token stored as a secret first (for example GITHUB_TOKEN), which the AI names when it starts the box.
• sandbox_sync: sent from your computer. Only files git tracks, plus new files .gitignore does not exclude; or only the tree of one commit. Ignored files (.env and node_modules in most projects) are not sent by default.

Keep files you do not want sent in .gitignore, or ask the AI to send only a commit.

Where do my code and data go?

• Boxes, the control plane, storage, the registry and the log service all run on AWS.
• When you use an iPhone simulator, the app you built is sent to a dedicated Mac host and installed and run there.
• A box connects wherever your programs connect: npm, GitHub, your dev, third-party APIs.
• Traffic from a box to your dev goes through ParallelSandbox to your connector; the connector talks to ParallelSandbox over TLS, and your services' own TLS (your database's SSL, for example) is not unwrapped between the box and your service.
• ParallelSandbox itself never gives your code to an AI model. What your AI sees (command output, screenshots) reaches your AI provider through your AI client, just as it does when you use it locally.
• Voice input in the app is turned into text as you speak; neither the audio nor the text is stored.

The full details are in the privacy policy.

When a box stops, is its disk really wiped?

Yes:

• When a box stops, its virtual machine is shut down and its disk file is deleted right away. Host disks are encrypted, and the whole disk is deleted when the host goes away.
• While a box is frozen, its memory and /work may be kept in encrypted storage; they are deleted when the box resumes or stops. There is also a 10-day upper limit as a safety net, which normal use never reaches.
• To be precise: this is "delete the files on encrypted disks", not overwriting every block.

What is kept, for how long, and can it be deleted?

To delete something, tell your AI (for example "delete this box's screenshots" or "clear the build cache"); it calls the REST endpoint in the table.

When you delete your account, running boxes stop and all of the above is deleted within 30 days at the latest. The REST details are on the REST page.

Who can open a box's URL? Can I add a login or limit it by IP?

• A box URL looks like https://<id>-<key>.box.parallelsandbox.com. The key is random, and a wrong one gets the same 404 as a box that does not exist; anyone with the full URL can open it, so treat it like a share link.
• To limit where it can be opened from, give the account an IP allowlist: tell your AI "open box URLs only to our office's 203.0.113.0/24", and it calls PUT /v1/box-access. About 3 seconds later every box URL of the account accepts only those IPs; anything else gets 403 and does not wake a frozen box. There is one list per account, at most 50 entries, and only IPv4 is matched for now; to turn it off, ask for an empty list.
• It suits teams with a company VPN or a fixed office IP. A colleague opening a review URL, or you testing on a phone over mobile data, must come from a listed IP (connect to the VPN first, say).
• There is no extra login: a review URL has to work for a colleague straight away, without a ParallelSandbox account.
• The takeover page and the app do not rely on the key in the URL: a takeover link is a one-time, expiring token from the control plane, and the app uses your sign-in.

Databases and test data

Is every box a fresh environment?

Yes. Every box starts from the same clean snapshot, and a database running in the box lives only until the box stops. The same box keeps it while frozen (see how long does a box stay?), but there is no persistent disk shared across boxes like a Kubernetes PVC.

How do my services' environment variables (DATABASE_URL and so on) get into a box?

Store them as an environment's service settings: import them from AWS ECS (with the SSM parameters and Secrets Manager values they reference), or upload a .env. A box started with that environment has /work/.sbx/env/<service>.env, and a changed service starts with it, configured exactly as on your dev. The settings are stored encrypted and the API returns only variable names; changed settings reach only boxes started afterwards.

Can I connect to my dev database directly?

Yes: an environment plus a connector, with the service settings from the previous answer. Note: when a changed service starts with your dev settings, its migrations and writes land in your dev database for real.

I have a set of test data I want to keep using, without migrating and seeding every time.

Keep that database in your own network (for example a Postgres in your dev just for tests) and let boxes reach it through an environment's connector. The data and the migration state stay with you, and every box carries on from where the last one left it. This is the only way to keep it for good today: ParallelSandbox does not keep the databases inside boxes for you.

I want a clean database every time.

Run psbx-testdb up <name> in the box: it starts a fresh Postgres 16 (or MySQL 8.0 with --mysql) and writes its DATABASE_URL to /work/.sbx/testdb/<name>.env; psbx-testdb reset <name> empties it again, and psbx-testdb gotest ./... gives every Go package a database of its own. Start other databases with your usual docker compose.

In one line: what stays and what does not?

• Does not stay: everything inside the box (code, containers, databases, /work) is gone when the box stops.
• Stays: what is in your own network (a database reached through the connector), images published to the registry, the build cache, and the stored files in the table above, each with its own limit.

Secrets

Where are secrets stored, and how do they reach a box?

• One list for the whole account, stored encrypted in the control plane. Not one set per box.
• Nothing goes into a box by default. The AI names the ones it needs when it starts the box, the box receives them the moment it is claimed, and they become environment variables of every command; they disappear with the box.
• A stored value cannot be read back: tool results, sandbox_status and platform logs only show names.
• Inside the box a secret is an environment variable. When a command prints it, what comes back to your AI has it masked as **** (values of 8 characters or more), as are the secret-looking dev settings an environment puts in the box; files in the box, such as a log the program writes, still hold the real value, so do not fetch them to your AI if they may contain one.
• Do not store ParallelSandbox's own API key as a secret; the box does not need it.

Is there a settings screen?

Yes: in app.parallelsandbox.com, the gear at the top right → Settings → Secrets. You can add, replace and delete them; it lists names and when each was last updated, and never shows a value. A value typed in the app never passes through your conversation with the AI, so it never reaches your AI provider; when the token is in your hands, use this. Your AI can also store one over REST (Secrets).

What if my program needs AWS permissions (S3, SQS)?

Do not store long-lived keys. Name an AWS role on the environment, and the box trades an OIDC token for temporary credentials that expire after an hour, the same way GitHub Actions connects to AWS (AWS permissions inside a box). ParallelSandbox holds no long-lived access to your AWS account.

Cost

• A box is charged per minute from the moment it is ready; frozen boxes are free. It freezes after 10 minutes with no activity, so a box you forgot to stop does not keep burning credits.
• Outbound traffic, logs and stored files are metered separately; environments and connectors are free. Rates are on Credits.

Example repos

Every tool call is on the example repos page. A full example with several services, a dev split between AWS and an office network, connectors, and using a changed service from another box is in team setup.