Skip to main content
Bring your own AI coding agent, or your own scripts, to a Base44 app by connecting to its sandbox. The sandbox is a private cloud environment that holds the code for whichever branch is currently active in the app editor, and runs its development server. It’s the same environment, and the same code, that the Base44 app editor itself edits, with no fork or copy to keep in sync. When you write a file through a sandbox command, you are changing your real app directly, on its active branch, the same way the app editor would. This lets you develop an app with your own tools instead of the app editor, with no local checkout and nothing to install. Work on an app from a machine that has no copy of it, or script a change across an app you built entirely in the app editor.
Editing through the sandbox is not 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, but reaching the app’s public site still takes the same publish step it would for a change made 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.
The sandbox itself is a live compute 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, since it lives in git rather than in that process. If the sandbox is not currently running, the first command starts it up, and that call takes longer than the ones after it.

​
Two ways to connect

The sandbox exposes the same set of operations through two surfaces, backed by the same implementation. Use whichever fits your setup.
  • CLI: Suits anything running on your own machine, including a local coding agent and your own scripts. Authenticate once with base44 login, then target the app with --app-id or the BASE44_APP_ID environment variable. No local project is required.
  • MCP server: Suits an AI assistant that connects over MCP, including web-based assistants that cannot run a CLI at all. Connect it once and authorize with OAuth.
The fastest way to start with your own coding agent is to use Send to Coding Agent in the Base44 app editor. On desktop, open More actions (the three dots next to Publish, in the top right corner) and select Send to Coding Agent. Pick a local CLI agent or a web chat, and it hands you a ready-made prompt to paste in, so you don’t have to set any of this up by hand. It is not offered for mobile apps or apps with unmanaged source code.

​
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 is 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. Once a commit lands:
  • The change is visible in the Base44 app editor.
  • It’s safe even if the sandbox’s compute environment gets recycled after sitting idle, since a new one always starts from your latest commit rather than an older snapshot.
  • It is included the next time you publish the app.
Structured resources sync the same way: unlike a local project, where you’d run entities push or functions deploy after adding a file, creating base44/functions/send-email/entry.ts in the sandbox is all it takes to add that function.
  • Do not run deploy, functions deploy, entities push, or the other push commands against an app you are editing in its sandbox. Those commands sync a local project to Base44, and there is no local project when working 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.

​
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 is 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 is 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.

​
Permissions

Two separate checks gate access to the sandbox: whether you can access this app at all, and 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 do not 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 cannot 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 does not add it. So if the reading commands work but the changing ones fail with NOT_AUTHORIZED, you are 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 are not 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 so that your agent can work with the skills the app has installed. 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