Skip to content
AgentBox Documentation

List sandboxes

You can list sandboxes using the Sandbox.list() method.

The Sandbox.list() method returns a list of SandboxInfo objects.

Note: Once you have information about running sandbox, you can connect to it using the Sandbox.connect method.

from agentbox import Sandbox

# Create a sandbox with metadata
sandbox = Sandbox(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxxx",
    template="wemmodr8mb2uk3kn7exw",
    timeout=60,
    metadata = {
        "name": 'My Sandbox'
        })

# List all running sandboxes.
running_sandboxes = sandbox.list(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxxx",
)
running_sandbox = running_sandboxes[0]

print('Running sandbox metadata:', running_sandbox.metadata)
print('Running sandbox id:', running_sandbox.sandbox_id)
print('Running sandbox started at:', running_sandbox.started_at)
print('Running sandbox template id:', running_sandbox.template_id)

The code above will output something like this:

Running sandbox metadata: {'name': 'My Sandbox'}
Running sandbox id: isqb3syh3dk72mpw4x7zs-BRD-3D45C8D35265404F
Running sandbox started at: 2025-07-16 03:23:28.078395+00:00
Running sandbox template id: wemmodr8mb2uk3kn7exw

Filtering sandboxes

Section titled “Filtering sandboxes”

You can filter sandboxes by specifying Metadata key value pairs. Specifying multiple key value pairs will return sandboxes that match all of them.

This can be useful when you have a large number of sandboxes and want to find only specific ones. The filtering is performed on the server.

from agentbox import Sandbox
from agentbox.sandbox.sandbox_api import SandboxQuery

# Create sandbox with metadata.
sandbox = Sandbox(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxxx",
    template="wemmodr8mb2uk3kn7exw",
    timeout=60,
    metadata={
        "env": "dev",  
        "app": "my-app",  
        "user_id": "123",  
    },
)

# List running sandboxes that has `user_id` key with value `123` and `env` key with value `dev`.
running_sandboxes = Sandbox.list(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxxx",
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev", 
        }
    ),
)
running_sandbox = running_sandboxes[0]
print('Running sandbox list query metadata:', running_sandbox.metadata)
print('Running sandbox list query id:', running_sandbox.sandbox_id)
print('Running sandbox list query started at:', running_sandbox.started_at)
print('Running sandbox list query template id:', running_sandbox.template_id)

The code above will output something like this:

Running sandbox list query metadata: {'app': 'my-app', 'env': 'dev', 'user_id': '123'}
Running sandbox list query id: in0mnr00x5axebe5gc250-BRD-81686B43867A4F4A
Running sandbox list query started at: 2025-07-18 07:13:15.766336+00:00
Running sandbox list query template id: wemmodr8mb2uk3kn7exw