Sandboxes

Documentation Index

Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

Use sandboxes to control where and how agents run tools, including file system access, network access, and the runtime environment. Each sandbox isolates tool execution from resources outside its allowed scope. Poolside supports different execution options depending on where the agent runs. Some options use managed sandbox definitions, and some do not: Poolside Assistant and the pool CLI

• Local environment: Runs on the user’s machine, using any sandbox settings configured there. Poolside enables this option by default. You do not create it from the Sandboxes page.
• Managed local sandbox: Runs on the user’s machine with organization-managed sandboxes.

Poolside Chat

• Local browser: Runs in Poolside Chat in the user’s browser. Select this option when you want an agent to be available in Poolside Chat. It does not use a managed sandbox definition.

Create managed local sandbox definitions from Agents > Sandboxes, then enable them on the agents that need them. For information on configuring sandbox behavior locally when running agents with the pool CLI, see Tool permissions. For a complete reference of supported settings.yaml keys, see Settings file reference.

​

When to use a sandbox

Use a sandbox when you want to:

• Run agent tools in an isolated environment
• Control network access for tool execution
• Restrict how agents interact with project files
• Use custom runtime environments or container images
• Apply consistent security boundaries across agent workflows
• Allow agents to run approved tools without repeated manual approvals

Do not use a sandbox when:

• Tool execution does not require isolation
• Network or file system restrictions are unnecessary
• Agents are not running tools that execute code or external commands

​

Access and security

Role-based permissions and agent configuration determine who can access a managed sandbox definition and how agents can use it. Local sandbox settings in a user’s settings file apply to that user’s local environment. Manage local sandbox definitions in the Poolside Console.

​

Role-based permissions

Role permissions determine whether a user can create, use, or manage sandbox definitions. A user must have the Use Sandbox Definitions permission to run an agent in a sandbox. For a complete list of permissions, see Permissions reference.

​

Agent access

Choose which sandbox definitions an agent can run in during agent configuration. Configure sandbox settings, then enable each managed sandbox explicitly for the agents that need it. See Managed agents for details.

• Enable a sandbox for an agent before the agent can use it
• Use managed local sandboxes when agents run in Poolside Assistant or the pool CLI

• Sandbox settings apply at runtime
• The sandbox definition limits agent execution

An agent can run in a sandbox only if:

• The agent has that sandbox enabled, and
• The user running the agent has permission to use that sandbox

Enabling a sandbox for an agent does not give users permission to use it.

​

How agents use sandboxes

When an agent runs in a sandbox:

• Its tools run within the sandbox environment
• Workspace access settings limit file system access
• The egress allowlist restricts network access
• The sandbox isolates execution from other agents and sandboxes
• Local stdio MCP servers are subject to network restrictions, and remote MCP servers that use HTTP or server-sent events (SSE) are not subject to those restrictions

In Poolside Assistant and the pool CLI, an agent can use the Local environment option or one or more Managed local sandbox definitions. In Poolside Chat, an agent can run with the Local browser option, which runs in the user’s browser rather than in a managed sandbox.

​

How sandboxes run

Tool commands run inside an isolated containerized environment, not directly in Poolside application processes. A sandbox definition controls the container image, workspace access, and network policy. The selected execution environment enforces those settings when the agent runs tools.

​

Managed local sandboxes

In a managed local sandbox, your tool commands run in a container on your machine. The container uses the configured image and receives workspace mounts according to the sandbox’s Workspaces Access setting. The container persists for the sandbox session, and each tool command runs inside that constrained environment. When Workspaces Access is Read Write, your workspace is mounted directly into the container so file changes appear on the host. When Workspaces Access is Read Only, your workspace is mounted read-only and agent changes are staged in writable scratch space. After you review the changes, you can apply them to your workspace or discard them. If you configure Deny All or Allowlist network policy, the sandbox runs on an isolated Docker network. For allowlisted egress, HTTP and HTTPS traffic routes through a proxy container that enforces the configured domains.

​

Remote sandbox execution environments

Remote sandboxing is deployment-dependent. In deployments that enable it, each sandbox is scheduled through the Kubernetes API as a Job that creates one sandbox pod. The configured container image supplies the pod’s root filesystem. A sandbox daemon starts inside the pod as the entry process. Tool requests are forwarded to that in-pod daemon, and tool commands run as child processes inside the same pod. The sandbox pod provides the primary execution boundary. Depending on deployment configuration, the pod can run with standard container isolation or with a Kubernetes RuntimeClass, such as gVisor or Kata Containers, for an additional runtime isolation layer. Network policy controls egress from remote sandbox pods. A deployment can allow public egress while blocking internal networks and cloud metadata services, block egress, or route egress through a proxy that enforces allowed destinations. Remote sandbox state is tracked through Kubernetes Jobs, Pods, labels, and annotations. A sandbox ends when the caller shuts it down, when its maximum time to live expires, when it sits idle past the configured idle timeout, or when Kubernetes terminates the pod because of a crash, resource limit, or eviction.

​

Use sandboxes for local development

For local development, treat the sandbox as an isolated runtime for the agent, not as a full development container that replaces your host environment. For local development:

• Your project files stay on your host, even when the agent runs in a sandbox.
• Depending on workspace access, the agent’s file changes appear on your host immediately or after review.
• By default, services running inside the sandbox are not exposed to your host.
• Starting a new conversation starts a new sandbox session. When you return to an earlier conversation or restart your IDE, you continue where you left off in the same sandbox session.

To reuse build artifacts and other host-side state across sandbox sessions, use volume mounts with sandbox.filesystem.mounts to mount extra host paths into the sandbox. See Local sandbox. If you change the sandbox definition while a sandboxed conversation is already running, start a new conversation to pick up the updated sandbox configuration. Recommended development flow:

1. Start the development server on your host machine.
2. Run the agent with sandboxing enabled.
3. Let the agent edit files in the workspace.
4. If workspace access is Read Write, the changes appear on your host immediately.
5. If workspace access is Read Only, review and apply the changes back to your host before you test them.

Use this approach when you want the safety and policy controls of sandboxing while still running your app, server, and port-bound processes on the host.

​

Create a sandbox

Prerequisites

• You have the Create Sandbox Definition permission.

• For managed local sandboxes, Docker is available in the execution environment.

Steps

1. In the Poolside Console, navigate to Agents > Sandboxes.
2. Click New Sandbox.
3. Enter a Name.
4. Select an Execution Environment. This choice determines where the sandbox runs and which runtime and infrastructure it uses to execute tools.
5. Optional: Specify a Container Image to include specific dependencies, libraries, or tools required for your agent. If you do not specify an image for a managed local sandbox, Poolside defaults to ubuntu:22.04. For managed local sandboxes, the sandbox uses whatever images your local Docker engine can already pull or has locally, including private images from registries Docker is already authenticated to. Poolside does not ask for registry credentials in the Poolside Console.
6. For managed local sandboxes, select a Workspaces Access option to control how tools running in the sandbox can interact with project files.
   • Read Write: Tools can read and modify files
   • Read Only: Tools can read files but cannot modify them
7. Configure the Network Policy to control which external network destinations the sandbox can access. Select one of the following options:
   • Deny All: Blocks all outbound network access from the sandbox.
   • Allow All: Allows outbound network access to any external destination.
   • Allowlist: Restricts outbound network access to explicitly allowed destinations. Selecting this option displays the Network Egress Allowlist section, where you can add destinations such as domains, subdomains, or CIDR blocks. The sandbox blocks any outbound network access you do not explicitly allowlist.
8. Click Create Sandbox.

Next steps After creating a sandbox:

1. Assign the sandbox to one or more agents. Sandboxes are not available to agents by default. Enable managed local sandboxes for Poolside Assistant and the pool CLI.
2. Verify that the sandbox configuration matches your security requirements, including workspace access and network egress rules.
3. Test agent tool execution using the sandbox to confirm tools run successfully and access is correctly restricted.
4. Refine sandbox settings as needed based on agent behavior or security requirements.

​

Delete a sandbox

Deleting a sandbox removes it from all agents that reference it. Agents that use the deleted sandbox can no longer execute tools in that environment until you assign a different sandbox. Prerequisites

• You have the Manage Sandbox Definitions permission.

Steps

1. In the Poolside Console, navigate to Agents > Sandboxes.
2. Select the sandbox you want to delete.
3. Click Delete.