Skip to main content
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.
  • Custom sandboxes aren’t available on bring-your-own-cloud deployments.

​
Create a sandbox

1

Ask Research

In a Research session, 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.