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. Configure each sandbox independently and assign it explicitly to agents. 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 sandbox definition and how agents can use it. You can create local sandbox definitions in a settings file, but server-side permissions determine whether agents can use them.

​

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. Enable each sandbox explicitly for the agents that need it. See Agents for details.

• Enable a sandbox for an agent before the agent can use it
• 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 (HTTP or SSE) are not subject to those restrictions

​

Create a sandbox

Prerequisites

• You have the Create Sandbox Definitions permission.
• You know the execution environment and security settings you want to apply.
• Docker is available in the execution environment, with support for volume mounts.
• For file system sandboxing, 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, 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. Select a Workspace 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.
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. Steps

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