> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud sandbox

> The private cloud environment that holds your app's code, and how to work in it without a local copy

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](/developers/app-code/sandbox/bring-your-own-agent) to an app you built in the app editor.

<Warning>
  You need a [**Builder plan**](/Account-and-billing/Billing-and-plans) or higher to reach an app's sandbox from outside the app editor. Without one, commands fail with `PREMIUM_REQUIRED`.
</Warning>

## When to use the sandbox

You can work on the code of an app you built in the app editor in the following ways:

| Option                                                              | Use it when                                                                         | Setup required                                                                       |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [Code tab](/developers/app-code/editor/code-tab)                    | You want a quick edit in the browser.                                               | None.                                                                                |
| Cloud sandbox                                                       | You want your own coding agent or scripts to change the app without downloading it. | Sign in with the CLI, or connect over MCP.                                           |
| [GitHub integration](/developers/app-code/local-development/github) | You want the code in your own repo and a full local setup in your IDE.              | An app owner connects a repo once. Each machine then clones it and installs the CLI. |
| [Eject](/developers/references/cli/commands/eject)                  | You want a copy of the code outside Base44 that doesn't sync back.                  | One command.                                                                         |

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:

* **[CLI](/developers/references/cli/get-started/overview):** For a coding agent or scripts running on your own machine. No local project is required. For setup, see [Connect a local agent with the CLI](/developers/app-code/sandbox/bring-your-own-agent#connect-a-local-agent-with-the-cli).
* **[MCP server](/developers/backend/overview/mcp-server):** For an AI assistant that connects over MCP, including web-based assistants that can't run a CLI. For setup, see [Connect an agent over MCP](/developers/app-code/sandbox/bring-your-own-agent#connect-an-agent-over-mcp).
* **[App Management API](/developers/references/apps-api/get-started/overview):** For your own integrations, using the endpoints listed below.

| Operation               | CLI command                                                                    | MCP tool            | API endpoint                                                              |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------- |
| List a directory        | [`sandbox ls`](/developers/references/cli/commands/sandbox-ls)                 | `list_directory`    | [List app files](/api-reference/list-app-files)                           |
| Read files              | [`sandbox read`](/developers/references/cli/commands/sandbox-read)             | `read_file`         | [Read app files](/api-reference/read-app-files)                           |
| Search file contents    | [`sandbox grep`](/developers/references/cli/commands/sandbox-grep)             | `grep`              | [Search app files](/api-reference/search-app-files)                       |
| Create a file           | [`sandbox write`](/developers/references/cli/commands/sandbox-write)           | `write_file`        | [Write an app file](/api-reference/write-an-app-file)                     |
| Change an existing file | [`sandbox edit`](/developers/references/cli/commands/sandbox-edit)             | `edit_file`         | [Edit an app file](/api-reference/edit-an-app-file)                       |
| Run a shell command     | [`sandbox run`](/developers/references/cli/commands/sandbox-run)               | `run_command`       | [Run a sandbox command](/api-reference/run-a-sandbox-command)             |
| Save a restore point    | [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) | `create_checkpoint` | [Create a sandbox checkpoint](/api-reference/create-a-sandbox-checkpoint) |

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`](/developers/references/cli/commands/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](/Building-your-app/working-with-branches), run [`branches list`](/developers/references/cli/commands/branches-list) to find its exact name, then pass [`--branch <name>`](/developers/references/cli/commands/introduction#target-a-branch) on each sandbox command. Reads and edits then apply to that branch only.

## Changes save automatically

A [`sandbox write`](/developers/references/cli/commands/sandbox-write) or [`sandbox edit`](/developers/references/cli/commands/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`](/developers/references/cli/commands/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`](/developers/references/cli/commands/entities-push) or [`functions deploy`](/developers/references/cli/commands/functions-deploy) after adding a file. In the sandbox, creating `base44/functions/send-email/entry.ts` is all it takes to add that function.

<Warning>
  **Two rules when editing in a sandbox:**

  * Don't run [`deploy`](/developers/references/cli/commands/deploy), [`functions deploy`](/developers/references/cli/commands/functions-deploy), [`entities push`](/developers/references/cli/commands/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.
</Warning>

## 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`](/developers/references/cli/commands/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.

<Warning>
  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.
</Warning>

## 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:

| Commands                                                             | Permission needed               |
| -------------------------------------------------------------------- | ------------------------------- |
| `sandbox ls`, `sandbox read`, `sandbox grep`                         | `apps:read`, granted by default |
| `sandbox write`, `sandbox edit`, `sandbox run`, `sandbox checkpoint` | `sandbox:write`                 |

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`](/developers/references/cli/commands/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

* [Bring your own agent](/developers/app-code/sandbox/bring-your-own-agent): Connect your own AI coding agent to an app's sandbox
* [CLI Overview](/developers/references/cli/get-started/overview): Install and use the Base44 CLI
* [Base44 MCP server](/developers/backend/overview/mcp-server): Connect an AI assistant to your Base44 account
* [GitHub Integration](/developers/app-code/local-development/github): Develop locally with a two-way sync to your repo instead
* [Project structure](/developers/backend/overview/project-structure): How Base44 project files are organized