Sandbox Backends

Remote and local execution backends for Sandbox and per-agent AgentConfig.execution_backend.

Package: elsai-agents-tools (AgentCore, Daytona) and elsai-agents (Local)
Import namespace: elsai_tools.sandbox, elsai.execution

These implement the SandboxBackend protocol — they are not agent tools. Pass a template or instance to Sandbox(backend=...).

← Prebuilt Tools overview · Sandbox concept

Backend	Extra	Isolation
LocalSandboxBackend	— (elsai-agents)	None — host subprocess (dev only)
AgentCoreSandboxTemplate	agent-core-code-interpreter	AWS Bedrock AgentCore VM
DaytonaSandboxTemplate	sandbox-daytona	Remote Daytona workspace

---

Installation

# AWS Bedrock AgentCore
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ \
  "elsai-agents-tools[agent-core-code-interpreter]==0.3.0"

# Daytona
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ \
  "elsai-agents-tools[sandbox-daytona]==0.3.0"

Requires elsai-agents>=0.3.0 for the sandbox execution model.

---

Import

from elsai.execution import LocalSandboxBackend
from elsai_tools.sandbox import AgentCoreSandboxTemplate, DaytonaSandboxTemplate

If an optional dependency is missing, the corresponding class is set to None at import time (the elsai_tools.sandbox package does not fail). Import from elsai_tools.sandbox — not from elsai_tools.code_interpreter.

---

Wiring with Sandbox

Templates expose build_for_session(session_id); SandboxManager materializes the live backend per workspace_id.

from elsai import Agent
from elsai.agent import AgentConfig
from elsai.execution import Sandbox, workspace_id_for_run
from elsai.plugins.sandbox import SandboxPlugin
from elsai_tools.sandbox import AgentCoreSandboxTemplate

async with Sandbox(
    workspace_id=workspace_id_for_run("my-run"),
    backend=AgentCoreSandboxTemplate(region="us-west-2"),
    ttl_seconds=7200,
    seed_from="/path/to/project",
) as sandbox:
    agent = Agent(
        config=AgentConfig(
            sandbox=sandbox,
            plugins=[SandboxPlugin()],
        ),
    )
    await agent.invoke_async("Run tests and summarize results")

---

LocalSandboxBackend

from elsai.execution import LocalSandboxBackend

Host-mounted workspace. No process isolation — commands run as subprocesses on the same machine.

Parameter	Required	Default	Description
workspace_root	Yes	—	Host directory used as the workspace root and default working directory.
timeout	No	120	Default command timeout in seconds. Commands exceeding this return exit code 124.
max_output_bytes	No	100000	Maximum combined stdout/stderr bytes captured. Longer output includes an (output truncated) marker.
inherit_env	No	True	Whether subprocesses inherit the parent process environment.
env	No	None	Additional environment variables (merged when inherit_env=True).

Environment: No Elsai-specific variables. With inherit_env=True (default), workspace subprocesses receive the host process environment. For local_dev + host prebuilt tools in CI, set BYPASS_TOOL_CONSENT=true — see Tool consent.

Development only

A warning is logged at initialization. Use AgentCore or Daytona for production workloads.

---

AgentCoreSandboxTemplate

from elsai_tools.sandbox import AgentCoreSandboxTemplate

Configuration template for session-scoped AgentCore Code Interpreter backends.

Parameter	Required	Default	Description
region	No	env / account default	AWS region for Bedrock AgentCore.
identifier	No	None	Code interpreter identifier override.
session_timeout_seconds	No	900	Remote session lifetime in seconds.

build_for_session(session_id)

Returns an AgentCoreSandboxBackend bound to session_id (typically the sandbox workspace_id).

AgentCoreSandboxBackend

Usually created via the template — not constructed directly in application code.

Parameter	Required	Default	Description
session_name	Yes	—	Session name bound to the workspace ID.
region	No	env default	AWS region.
identifier	No	None	Code interpreter identifier.
session_timeout_seconds	No	900	Remote session timeout.
auto_create	No	True	Automatically initialize the AgentCore session on create().
persist_sessions	No	True	Reuse session mapping across calls.

Backend notes:

• Wraps the same AgentCore Code Interpreter used by the legacy code_interpreter tool.
• execute() does not honor a per-command timeout argument — use session_timeout_seconds on the template or wrap calls with asyncio.timeout().
• seed_workspace reads files as UTF-8 text (errors="replace"). Binary assets may not round-trip correctly.

Environment variables (host process):

Variable	Required	Description
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Yes*	Standard boto3 credentials
AWS_SESSION_TOKEN	No	STS / assumed-role token
AWS_REGION	No	Region fallback when region= is omitted
AWS_PROFILE	No	Named boto3 profile

*Not required with an instance/task IAM role, or when equivalent values are resolved by boto3 another way.

Class method AgentCoreSandboxBackend.template(...)

Convenience for building an AgentCoreSandboxTemplate with the same parameters.

---

DaytonaSandboxTemplate

from elsai_tools.sandbox import DaytonaSandboxTemplate

Configuration template for session-scoped Daytona sandboxes.

Parameter	Required	Default	Description
api_key	No	env / Daytona default	Daytona API key.
api_url	No	env default	Daytona API URL.
target	No	env default	Daytona target.
default_timeout	No	900	Default command timeout in seconds.
sync_polling_interval	No	0.1	Seconds between polls while waiting for command completion.

When api_key, api_url, and target are all omitted, the Daytona SDK default client is used (typically environment-based configuration).

Environment variables (host process):

Variable	Required	Description
DAYTONA_API_KEY	Yes*	Daytona API key
DAYTONA_API_URL	No	API URL (default https://app.daytona.io/api)
DAYTONA_TARGET	No	Target runner (us, eu, …)
DAYTONA_JWT_TOKEN	Alt*	JWT authentication instead of API key

*Read from the environment when omitted on the template — see Daytona configuration.

build_for_session(session_id)

Returns a DaytonaSandboxBackend bound to session_id.

DaytonaSandboxBackend

Parameter	Required	Default	Description
session_name	Yes	—	Session name for logging and identification.
api_key	No	env default	Daytona API key.
api_url	No	env default	Daytona API URL.
target	No	env default	Daytona target.
default_timeout	No	900	Default command timeout. 0 means poll until the command completes (no wall-clock limit).
sync_polling_interval	No	0.1	Poll interval for command completion.
sandbox	No	None	Pre-created Daytona sandbox instance (testing).
daytona_client	No	None	Pre-created Daytona client (testing).

Backend notes:

• Extends BaseSandbox in elsai.execution — uses native Daytona filesystem APIs where possible.
• execute() creates an ephemeral process session per command, then polls until exit or timeout.
• Workspace paths are mapped to the sandbox work directory from sandbox.get_work_dir().

---

vs code_interpreter tool

	Sandbox + backend	code_interpreter prebuilt tool
Purpose	Full project workspace (shell + files)	Code-interpreter action API
Agent tools	execute, read_file, write_file, list_dir	code_interpreter with action payloads
Multi-agent sharing	Same Sandbox instance	Per-context via A2A
Recommended for	New sandbox execution workflows	Legacy or code-only AgentCore sessions

See Code interpretation.

---

Related

• Sandbox API
• Sandbox — Backends (concept)
• Sandbox — Overview