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

> ## Agent Instructions
> Enclave in these docs is the code and cloud security platform at enclave.ai. It is not Open Enclave, Intel SGX or other hardware enclaves, or enclave.gg.
> People use Enclave in the web app at https://app.enclave.ai or the desktop app. These docs describe no public Enclave API or CLI, so don't invent endpoints, commands, or config files.
> Connecting an integration needs a person to sign in and approve access in a browser. Tell the user the exact step to take instead of saying you completed it.

# Custom sandboxes

> Build a sandbox from a Dockerfile with the languages and tools your team needs, and start Research sessions on it.

Research runs commands in Enclave's default sandbox. When your team needs other languages, tools, or another Linux distribution, an owner or admin can build a **custom sandbox** from a Dockerfile. Everyone in the organization can then start a session on it.

## Before you start

* Creating, rebuilding, and deleting a sandbox needs permission to manage integrations: the **Owner** or **Admin** role. See [Roles and permissions](https://docs.enclave.ai/admin/roles.md).
* Custom sandboxes aren't available on [bring-your-own-cloud](https://docs.enclave.ai/deployment/byoc.md) deployments.

## Create a sandbox

**1. Ask Research**

In a [Research session](https://docs.enclave.ai/research/sessions.md), describe what you need and give it a name. For example: "I need a sandbox where the agent can run jq and protoc. Call it tools."

**2. Approve the Dockerfile**

Research writes a Dockerfile and shows a **Create the sandbox tools?** card with the base image and the Dockerfile. Review it and click **Approve**.

**3. Follow the build**

A build card shows the status (**Queued**, **Building**, **Testing**, **Ready**, **Build failed**, or **Cancelled**), the elapsed time, and the build log. Click **Cancel** to stop it.

When the build finishes, the session gets the result and Research tells you what to do next. If the build failed, Research explains why and can propose a fixed Dockerfile. You also get a notification, so you hear about it from any page.

A sandbox is saved only when its build passes. A failed or cancelled build changes nothing that members see.

To change a sandbox, ask Research to update it by name. It shows an **Update the sandbox** card. The current version stays in use until the new build passes.

### Dockerfile rules

* The Dockerfile starts from `enclave/base`, Enclave's default sandbox image, unless you need another operating system. Other base images must come from a public registry.
* There's no build context. `COPY` and `ADD` can't read local files, but `ADD` can download an `http(s)` URL or clone a git repository.
* A Dockerfile can be up to 64 KB and 100 instructions.
* A build can run for up to 30 minutes.

## Start a session on a sandbox

In a new session, click the sandbox picker in the composer and choose a sandbox under **Sandbox environment**. **Enclave default** is Enclave's own sandbox.

A session keeps its sandbox. To use another one, start a new session.

A sandbox that's rebuilding shows **Rebuilding** in the picker. New sessions use its last successful build until the new one passes.

## Manage sandboxes

Go to **Settings → Sandboxes** to see your organization's sandboxes, their status (**Ready** or **Rebuilding**), and when the build in use was made.

Owners and admins click **Manage** to see the live Dockerfile and the log of the latest build, and to:

* **Rebuild** the sandbox from its Dockerfile.
* **Cancel** a build that's running.
* **Delete** the sandbox. Sessions that use it can't start their sandbox again, and ask you to start a new session.

When Enclave updates its sandbox software, a custom sandbox rebuilds automatically the next time someone starts a session on it. Sessions use the last successful build until then.

## Limits

* 3 sandboxes per organization. A new sandbox whose first build is running counts toward the limit.
* 20 builds per organization in any 24 hours. Rebuilds that Enclave starts after an update don't count.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.