> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolte.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Sandboxes
> Understand the isolated cloud environment the Revolte AI agent uses to read, write, and run your code.
A **sandbox** is the isolated, disposable cloud container the Revolte AI agent works in whenever it needs to touch a real codebase—cloning a repository, editing files, running shell commands, or executing tests. Every AI Chat thread and every automated workflow run gets its own sandbox, scoped to that single thread or run, so agent activity never touches your local machine or a shared environment.
Sandboxes power both interactive **AI Chat** sessions and automated **[Jira Workflow](/workflows/your-first-Autonomous-workflow)** runs. Whenever you see "Sandbox Provisioning" in an agent run's execution stages, or a live **Code** tab in an AI Chat thread, it's backed by a sandbox.
## How a sandbox is set up
When a sandbox starts, it's set up in one of two ways:
* **Connected to a repository**: If your thread or workflow is linked to a repository, the sandbox authenticates with your Git provider and clones the target branch, then checks out a dedicated working branch for the agent's changes.
* **Fresh project**: If no repository is connected yet, the sandbox initializes an empty local Git project. You can link it to a remote repository later and push the work the agent has done.
From there, the agent can run shell commands, read and write files, and validate its own changes—all inside that container.
## Sandbox lifecycle
A sandbox moves through the following states over its lifetime:
| Status | Meaning |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provisioning** | The sandbox container is being created and started. This is the "Sandbox Provisioning" stage you see in agent run details. |
| **Running** | The sandbox is live and reachable—the agent can execute commands, and (in AI Chat) the **Code** and **File changes** panels become available. |
| **Timeout Warning** | The sandbox has been idle and is about to be torn down. |
| **Deprovisioning** | Teardown is in progress—the container is being stopped and released. |
| **Stopped** | Teardown finished cleanly; the sandbox no longer exists. |
| **Error** | Something went wrong during setup or execution; the sandbox is torn down automatically. |
| **Quota Depleted** | Your organization's monthly sandbox usage has been exhausted; the sandbox is stopped. |
### Inactivity timeout
Sandboxes aren't kept running indefinitely. If a sandbox sits idle, Revolte warns you it will be torn down in about a minute, then automatically deprovisions it to free up resources.
**Does that mean my changes are gone?** Not if your thread is linked to a repository. Just before teardown, Revolte automatically commits and pushes whatever the agent had changed as a draft commit to the working branch on your Git provider—so the work survives even if you weren't there to save it.
This safety net depends on a linked repository to push to. If you start a thread as a **fresh project** (no repository connected yet) and let it idle out before linking one, there's nowhere for that draft commit to go—the attempt fails silently and those changes are lost with the container. Link a repository, or commit manually, before stepping away from an unlinked sandbox.
Reopening the thread afterward provisions a fresh sandbox, picking up from the last commit that made it out—not from the exact in-progress state you left.
### Monthly sandbox hours
Sandbox compute time is tracked against your organization's monthly allotment, which scales with your plan:
| Plan | Sandbox hours / mo | Available sandbox sizes |
| :---------------------- | :----------------- | :------------------------------------- |
| **Free** | 50 hrs | Small |
| **Starter** | 150 hrs | Small, Medium |
| **Growth** | 240 hrs | Small, Medium, and additional variants |
| **Enterprise / Custom** | Custom | Custom variants |
If your organization's monthly sandbox hours are used up, any active sandboxes are stopped and you'll see a notice explaining that usage has been depleted for the billing period. See [Pricing & Usage Plans](/pricing) for full plan details.
## Sandbox size
When starting a new AI Chat thread, you can choose the size of the sandbox the agent runs in:
| Size | Resources |
| :--------- | :------------------- |
| **Small** | 2 vCPU / 2 GB memory |
| **Medium** | 2 vCPU / 4 GB memory |
| **Large** | 2 vCPU / 8 GB memory |
Pick a larger sandbox for workloads with heavier build steps, larger dependency installs, or more memory-intensive test suites. Automated Jira Workflow runs use a size appropriate for the task automatically.
## Working inside a sandbox
While a sandbox is **Running**, an AI Chat thread exposes two live views into it:
* **Code**: A full in-browser code editor connected directly to the sandbox's filesystem, so you can inspect (or edit alongside the agent) the exact state of the code as the agent works.
* **File changes**: A live diff view of every file the agent has created or modified via its Write/Edit tool calls, so you can review changes as they happen rather than waiting for a final summary.
Both panels require a running sandbox—they stay disabled while a sandbox is provisioning or has been torn down.
## Getting your code out
A sandbox's filesystem is disposable, so nothing in it persists past its lifecycle unless it's committed out (see [Inactivity timeout](#inactivity-timeout) for what happens automatically):
* **In AI Chat**, you can link the sandbox's local repository to a remote and commit and push the agent's changes at any time—Revolte can also generate a commit message for you.
* **In Jira Workflow runs**, the agent commits its changes and opens a Pull Request against your connected repository automatically, so you review and merge through your normal Git workflow.
## Next steps
* [Workflow Overview](/workflows/overview) — Compare interactive AI Chat with automated Jira workflows.
* [Automate Work from Jira](/workflows/your-first-Autonomous-workflow) — Watch sandbox provisioning happen in a real run.