Skip to main content
Every Base44 app has a sandbox: a private cloud environment that holds the app’s code and runs its development server. It’s the same environment, and the same code, that the app editor uses, with no fork or copy to keep in sync. Connect to it via the CLI, an MCP client, or the API to read, search, edit, and run commands against your app from any machine, with no local checkout and nothing to install. When you write a file through the sandbox, you’re changing your real app directly, the same way the app editor would. The most common reason to do this is to bring your own coding agent to an app you built in the app editor.
You need a Builder plan or higher to reach an app’s sandbox from outside the app editor. Without one, commands fail with PREMIUM_REQUIRED.

​
When to use the sandbox

You can work on the code of an app you built in the app editor in the following ways: The sandbox and the GitHub integration overlap the most, since both let you work with your own tools. The difference is where the code lives while you work. With the GitHub integration, you develop in a local clone, and your changes reach Base44 when they’re merged to main. With the sandbox, you work on the app’s code in place. There’s nothing to download, a web-based assistant can use it, and every change appears in the app editor’s live preview as soon as it’s made.

​
Ways to connect

You can reach the sandbox in the following ways: Connectors don’t go through the sandbox file system, so they aren’t in the table above. To set up a connector on an app you’re working with this way, use connectors initiate instead. It targets the same app id directly, without a sandbox or a local project.

​
Branches

Sandbox commands target the app’s main branch unless you say otherwise. To work on another branch, run branches list to find its exact name, then pass --branch <name> on each sandbox command. Reads and edits then apply to that branch only.

​
Changes save automatically

A sandbox write or sandbox edit call commits the change for you as part of the same request, before the command returns, so there’s no separate save, deploy, or push step. A file change made through sandbox run, such as rm or mv, commits a few seconds later instead, once a short debounce window closes. If you write or edit again before an earlier debounced commit has landed, the new call waits on it and fails with COMMIT_FLUSH_PENDING if it can’t confirm that commit finished in time. Structured resources sync the same way. In a local project, you’d run entities push or functions deploy after adding a file. In the sandbox, creating base44/functions/send-email/entry.ts is all it takes to add that function.
Two rules when editing in a sandbox:
  • Don’t run deploy, functions deploy, entities push, or the other push commands against an app you’re editing in its sandbox. Those commands sync a local project to Base44, and there’s no local project when you work with a sandbox.
  • If your last action was a shell command run through sandbox run rather than a write or edit call, its commit is still a moment behind. Give it a few seconds before you disconnect.

​
Editing and publishing

Editing through the sandbox isn’t the same as publishing. Your edit becomes part of the app’s code right away and shows up in the app editor and its live preview. Reaching the app’s public site still takes the same publish step as a change made in the app editor.

​
Checkpoints

A checkpoint is a restore point in the app’s version history, anchored to a specific commit. Create one with sandbox checkpoint to mark a known-good state, then restore it from the app editor if a later change goes wrong. Pending changes are committed before the checkpoint is taken, so it always captures your latest code.

​
Working alongside the app editor

Your coding agent and the Base44 app editor can work on the same app at the same time. There’s no lock to acquire and no session to release. Changes from either side land in the same place, so treat it the way you would treat a colleague editing the same project.
There’s no merge step. If your coding agent and the app editor change the same file at the same time, whichever write lands last wins, and the earlier change is gone. Avoid having both sides touch the same file in the same stretch of work.

​
Starting and stopping

The sandbox is a running process, not just storage. It spins down when it sits idle for a while and spins back up on the next command. Your code is unaffected either way. Committed changes live in git, and a restarted sandbox always starts from your latest commit. If the sandbox isn’t running, the first command starts it up, which means that call is likely to take longer than the ones after it.

​
Permissions

Two separate checks gate access to the sandbox. One is whether you can access the app at all, and the other is whether your current session was granted write access to it.

​
App access

You need admin access to the app itself, either as a workspace admin or as a collaborator on this specific app. Access is checked on every call, so a change to your workspace role takes effect immediately. A plain workspace viewer can’t reach the sandbox at all. The one exception is a viewer who also holds a legacy per-app editor role from before your workspace moved to role-based access. That combination can still read from the sandbox, but not change anything. Superagents don’t support the sandbox commands.

​
Session scope

Beyond app access, reading and changing the sandbox require different permissions on your session: Your session’s permissions are fixed when it’s created and can’t be widened later. The CLI asks for sandbox:write during base44 login, and over MCP you grant it at the OAuth consent step. Renewing an existing session doesn’t add it. So if the reading commands work but the changing ones fail with NOT_AUTHORIZED, you’re on a session that never had sandbox:write. Run base44 login again, or reconnect the MCP server and approve sandbox access, to start a session that has it.

​
Limits and guardrails

File commands are confined to the app root. Absolute paths and paths that climb above the root are rejected with PATH_OUTSIDE_SANDBOX. The .agents and .git directories aren’t reachable from the file commands, and fail with PROTECTED_PATH, because they hold your app’s secrets and repository credentials. The one exception is .agents/skills, which you can read and write. Across the whole feature, you’re capped at 120 read requests, 60 change requests, and 30 run commands per minute, per app. Going over any of these fails with RATE_LIMITED. Each command’s own reference page covers its size and count limits, such as how many paths sandbox read accepts or how large a file sandbox write allows.

​
See also