Sandboxes

​

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.

​

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.

​

Create a sandbox

Prerequisites

• You have the Create Sandbox Definitions permission.

• For managed local sandboxes, Docker is available in the execution environment, with support for volume mounts.
• For managed local sandboxes with read-only workspace access, the base container image includes fuse-overlayfs.

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 selects a default based on the workspace access mode you choose: ubuntu:22.04 for read-write access, or a built-in OverlayFS-based image for read-only access.
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.