Sandbox — Backends

An execution backend is where sandbox commands and file operations actually run. Pass a backend instance or template to Sandbox(backend=...).

Backend	Package	Isolation	Best for
LocalSandboxBackend	elsai-agents	None (host)	Local dev and tests
AgentCoreSandboxTemplate	elsai-agents-tools	AWS AgentCore VM	Production on Bedrock
DaytonaSandboxTemplate	elsai-agents-tools	Remote Daytona workspace	Remote dev environments

Full parameter reference: Sandbox backends API.

Local development

from pathlib import Path

from elsai.execution import LocalSandboxBackend, Sandbox, workspace_id_for_run

async with Sandbox(
    workspace_id=workspace_id_for_run("local-dev"),
    backend=LocalSandboxBackend(Path("/tmp/elsai-sandbox")),
    ttl_seconds=3600,
    seed_from=Path("./my-repo"),
) as sandbox:
    ...

What this shows:

Piece	Concept
LocalSandboxBackend	Uses a host directory — subprocesses run on your machine
No extra install	Ships with elsai-agents

Not isolated

Logs a warning at init. Do not use for production agent workloads with untrusted input.

Pair with SandboxMode.LOCAL_DEV on the per-agent advanced path if you also need host prebuilt tools alongside sandbox tools. Shared Sandbox attach uses production host-tool blocking — AgentConfig(sandbox=..., sandbox_mode=local_dev) raises ValueError at construction.

Environment: Subprocesses inherit the host process environment when inherit_env=True (default). Pass extra variables with env= on the constructor — see LocalSandboxBackend. For local_dev workflows that also use host prebuilt tools, set BYPASS_TOOL_CONSENT=true in CI — see Tool consent.

Secrets

Default seed excludes .env, *.pem, credentials.json, and secrets/ — see DEFAULT_SANDBOX_SEED_EXCLUDES. With LocalSandboxBackend, subprocesses can still see the host environment when inherit_env=True.

AWS Bedrock AgentCore

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

from elsai_tools.sandbox import AgentCoreSandboxTemplate

async with Sandbox(
    workspace_id=workspace_id_for_run(run_id),
    backend=AgentCoreSandboxTemplate(
        region="us-west-2",
        session_timeout_seconds=900,
    ),
    ttl_seconds=7200,
    seed_from="/path/to/repo",
) as sandbox:
    ...

What this shows:

Piece	Concept
AgentCoreSandboxTemplate	Config object; manager calls build_for_session(workspace_id)
AWS credentials on host	Agent never runs inside the VM with your API keys

Operational notes:

• Per-command timeout on execute is not honored — configure session_timeout_seconds or use asyncio.timeout() at the call site
• Project seeding reads files as UTF-8 text

Requires IAM permissions for Bedrock AgentCore Code Interpreter in your AWS account.

Environment variables (host process — or use an IAM role on EC2, ECS, Lambda, …):

Variable	Required	Notes
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Yes*	Standard boto3 credentials
AWS_SESSION_TOKEN	No	Temporary / assumed-role credentials
AWS_REGION	No	Used when region= is omitted on the template
AWS_PROFILE	No	Named AWS profile

*Not required when credentials come from an instance/task role, or when you pass region= explicitly and boto3 resolves credentials another way.

Daytona

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

from elsai_tools.sandbox import DaytonaSandboxTemplate

async with Sandbox(
    workspace_id=workspace_id_for_run(run_id),
    backend=DaytonaSandboxTemplate(
        api_key="...",  # or omit to use Daytona SDK env defaults
        default_timeout=900,
    ),
    ttl_seconds=7200,
    seed_from="/path/to/repo",
) as sandbox:
    ...

What this shows:

Piece	Concept
DaytonaSandboxTemplate	Creates remote Daytona workspace per session
Native FS APIs	File ops use Daytona filesystem; commands use ephemeral process sessions

Operational notes:

• Each execute call creates a short-lived process session and polls until completion
• default_timeout=0 waits until the command finishes with no wall-clock limit

Environment variables (host process — or pass api_key=, api_url=, target= on the template):

Variable	Required	Notes
DAYTONA_API_KEY	Yes*	API key from the Daytona dashboard
DAYTONA_API_URL	No	Defaults to https://app.daytona.io/api
DAYTONA_TARGET	No	Runner region (us, eu, …)
DAYTONA_JWT_TOKEN	Alt*	JWT from daytona login instead of API key

*When all constructor args are omitted, the Daytona SDK reads these from the environment (and optional .env).

Production flow — shared workspace

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

async def main() -> None:
    run_id = "feature-auth"
    async with Sandbox(
        workspace_id=workspace_id_for_run(run_id),
        backend=AgentCoreSandboxTemplate(region="us-west-2"),
        ttl_seconds=7200,
        seed_from="/host/monorepo",
    ) as sandbox:
        coder = Agent(
            config=AgentConfig(sandbox=sandbox, plugins=[SandboxPlugin()]),
        )
        reviewer = Agent(
            config=AgentConfig(
                sandbox=sandbox,
                sandbox_attach_mode=SandboxAttachMode.READ_ONLY,
                plugins=[SandboxPlugin()],
            ),
        )

        await coder.invoke_async("Implement JWT refresh in services/auth/")
        await reviewer.invoke_async("Review services/auth/ for security issues")

asyncio.run(main())

What this shows:

Piece	Concept
Remote backend + shared Sandbox	Production isolation with multi-agent file sharing
Read-only reviewer	Audit without write or execute access

Detach behavior is identical across backends — see Shared workspace — Attach and detach.

vs code_interpreter tool

	Sandbox + backend	code_interpreter prebuilt tool
Scope	Full project workspace	Code-interpreter session actions
Tools	execute, file ops via plugin	code_interpreter payload API
Multi-agent	Shared Sandbox	Per A2A context
Recommended	New workspace workflows	Legacy code-only sessions

See Code interpretation.

Optional import fallbacks

If bedrock_agentcore or daytona is not installed, the corresponding class in elsai_tools.sandbox is None. Install the matching extra before wiring production backends.

Related

• Overview — timeouts and TTL
• Shared workspace
• Sandbox backends API
• Sandbox API