Lifecycle

By default, a Sandbox stays alive for 5 minutes when started. You can customize this duration by passing the timeout. After the specified time elapses, the Sandbox will automatically shut down.

Tip: The timeout is measured in seconds.

Python[Sync]

from agentbox import Sandbox

# Create sandbox with and keep it running for 60 seconds.
# Note: The units are seconds.
sandbox = Sandbox(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

# Get sandbox information
info = sandbox.get_info()

print("init started_at:", info.started_at)
print("init end_at:", info.end_at)

Python[Async]

from agentbox import AsyncSandbox

# Create sandbox with and keep it running for 60 seconds.
# Note: The units are seconds.
sandbox = await AsyncSandbox.create(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

 # Get sandbox information
info = await sandbox.get_info()

print("init started_at:", info.started_at)
print("init end_at:", info.end_at)

Change sandbox timeout during runtime

You can change the Sandbox timeout while it is running by calling the set_timeout method:

When you call this method, the sandbox timeout will be reset to the new value you specify.

Tip: Tip: This is useful if you want to extend the sandbox lifetime dynamically. For example, you could start a sandbox with a 1-minute timeout and periodically call set_timeout each time a user interacts with it in your app.

Python[Sync]

from agentbox import Sandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = Sandbox(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
    template="wemmodr8mb2uk3kn7exw",
    timeout=60)

# Get sandbox information
info = sandbox.get_info()
print("init started_at:", info.started_at)
print("init end_at:", info.end_at)

# Change the sandbox timeout to 30 seconds.
# The new timeout will be 30 seconds from now.
sandbox.set_timeout(30)

# Get sandbox information
info = sandbox.get_info()
print("after set_timout, started_at:", info.started_at)
print("after set_timout, end_at:", info.end_at)

Python[Async]

from agentbox import AsyncSandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = await AsyncSandbox.create(
    api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
    template="wemmodr8mb2uk3kn7exw",
    timeout=60)

# Get sandbox information
info = await sandbox.get_info()
print("init started_at:", info.started_at)
print("init end_at:", info.end_at)

# Change the sandbox timeout to 30 seconds.
# The new timeout will be 30 seconds from now.
await sandbox.set_timeout(30)

# Get sandbox information
info = await sandbox.get_info()
print("after set_timout, started_at:", info.started_at)
print("after set_timout, end_at:", info.end_at)

Retrieve sandbox information

You can retrieve sandbox information like sandbox ID, template, metadata, started at/end at date by calling the get_info method in Python.

Python[Sync]

from agentbox import Sandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = Sandbox(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

# Retrieve sandbox information.
info = sandbox.get_info()

print(info)

# SandboxInfo(sandbox_id='ig6f1yt6idvxkxl562scj-419ff533',
#   template_id='u7nqkmpn3jjf1tvftlsu',
#   name='base',
#   metadata={},
#   started_at=datetime.datetime(2025, 3, 24, 15, 42, 59, 255612, tzinfo=tzutc()),
#   end_at=datetime.datetime(2025, 3, 24, 15, 47, 59, 255612, tzinfo=tzutc())
# )

Python[Async]

from agentbox import AsyncSandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = await AsyncSandbox.create(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

# Retrieve sandbox information.
info = await sandbox.get_info()

print(info)

# SandboxInfo(sandbox_id='ig6f1yt6idvxkxl562scj-419ff533',
#   template_id='u7nqkmpn3jjf1tvftlsu',
#   name='base',
#   metadata={},
#   started_at=datetime.datetime(2025, 3, 24, 15, 42, 59, 255612, tzinfo=tzutc()),
#   end_at=datetime.datetime(2025, 3, 24, 15, 47, 59, 255612, tzinfo=tzutc())
# )

Shutdown sandbox

You can shutdown the sandbox any time even before the timeout is up by calling the kill method.

Python[Sync]

from agentbox import Sandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = Sandbox(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

# Shutdown the sandbox immediately. result is bool
result = sandbox.kill()
print("result for kill:", result)

Python[Async]

from agentbox import AsyncSandbox

# Create sandbox with and keep it running for 60 seconds.
sandbox = await AsyncSandbox.create(
      api_key="ab_xxxxxxxxxxxxxxxxxxxxxxxx",
      template="wemmodr8mb2uk3kn7exw",
      timeout=60)

# Shutdown the sandbox immediately. result is bool
result = await sandbox.kill()
print("result for kill:", result)