Skip to main content

pydantic-ai-daytona

Daytona sandbox capability for Pydantic AI agents. DaytonaSandbox gives an agent an isolated cloud sandbox for running commands and working with files — a place to execute untrusted or model-generated code without touching the application host.

Installation

pip install pydantic-ai-daytona

Configuration

Get your API key from the Daytona Dashboard and set it in the environment (or a .env file):

export DAYTONA_API_KEY="your-daytona-api-key"

You can also pass api_key (plus optional api_url / target) directly to DaytonaSandbox.

Quickstart

from pydantic_ai import Agent
from pydantic_ai_daytona import DaytonaSandbox

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[DaytonaSandbox()],
)

result = agent.run_sync('Write a Python script that prints the first 10 primes and run it.')
print(result.output)

By default every agent run gets a fresh sandbox, created from the Daytona default snapshot and deleted when the run ends.

The capability contributes four tools:

Tool Purpose
run_command Run a shell command (pipes, redirection, and && work).
read_file Read a UTF-8 text file (up to max_read_bytes); pageable with explicit offset/limit.
write_file Write a UTF-8 text file, creating the parent directory.
list_directory List directory entries, marking directories with /.

Command output labels stdout and stderr separately, reports non-zero exit codes, and is truncated tail-first per stream, so errors and exit status remain visible. When a file read is cut short by the safety caps (or by limit), the result ends with the next offset to pass to continue reading — the model pages through large files the way grep -n numbers them.

Commands receive stdin from /dev/null (cat without arguments exits rather than waiting for input). Each command has its own process session, so concurrent tool calls can run in parallel. Bash is used when available; images without bash fall back to /bin/sh. The shell is detected once per opened session (owned or attached), with /bin/sh also used if the probe fails. Pipes, redirection, and bare exit N preserve their usual behavior.

Stdout and stderr are captured separately in unique sandbox temporary files. After completion or timeout, each stream is cut to its last max_output_bytes inside the sandbox before transfer; line limits are applied afterwards. Truncated streams retain a [... output truncated to the last <limit> ...] marker, where <limit> is a byte size (e.g. 50.0KB) or line count (e.g. 2000 lines). Output collection combines sizes, both bounded tails, and file removal in one API call (base64 framing adds bounded transfer overhead). Temporary files are removed best-effort, including on errors/cancellation.

A timeout now retains partial output rather than discarding it, followed by the applied deadline:

[stdout]
before
[timed out after 1s]

If neither stream has output, the first line is (no output). A timeout stops its process session without blocking the next command. Low-level DaytonaSandboxSession.exec() also returns bounded tails (50 KiB per stream by default; override with max_output_bytes=), with stdout_truncated / stderr_truncated flags and exit_code=-1 on timeout.

Sandbox lifecycle

Owned (default) — each run creates a sandbox and deletes it when the run ends:

DaytonaSandbox(snapshot='my-snapshot')          # or image='python:3.12-slim'

Cancellation during creation is deferred until the SDK create call finishes and the newly owned sandbox is deleted; only then is cancellation re-raised. Owned cleanup waits for deletion to finish. If deletion fails, the run's result is kept and a warning naming the sandbox id is logged (logger pydantic_ai_daytona._session), so you can delete it yourself. This can delay cancellation while creation/deletion completes; server-side auto-stop/auto-delete remains the backstop for failures or a process crash.

For fully untrusted code, block outbound network access at creation. Independently, ephemeral=True hardens cleanup: Daytona deletes the sandbox the moment it stops, even if your process crashed before its own cleanup ran.

DaytonaSandbox(network_block_all=True, ephemeral=True, labels={'app': 'support-agent'})

Attached — reuse a sandbox you manage elsewhere; stopped, archived, and paused sandboxes are restarted and never deleted by this capability (their owner or Daytona may still delete them). Startup transitions are awaited with a deadline; destroyed/destroying sandboxes are rejected rather than restarted:

DaytonaSandbox(sandbox_id='my-sandbox-id', env={'APP_MODE': 'agent'})

env is applied per command in both owned and attached sessions, and also at creation for owned sandboxes. Values are shell-quoted literally (including spaces, quotes, $HOME, and newlines). Bash preserves dashed variable names; on the sh fallback, environment variable names that aren't valid shell identifiers are dropped. Per-command values do not permanently change an attached sandbox's environment. An injected session supplies its own env; do not also pass env to DaytonaSandbox(session=...).

Unclassified Daytona errors from command and file operations trigger a control-plane probe. Session-opening paths (attached lookup, startup, and transition waits) map errors directly without probing. If the sandbox is deleted/destroying, or was stopped while idle, the operation raises DaytonaSandboxTerminalError instead of asking the model to retry. An inconclusive probe keeps the original retryable error; known missing-file/session-ended errors remain retryable and authentication errors remain terminal. Reattach to resume an idle-stopped sandbox.

Injected session — share one sandbox across several runs while controlling its lifetime yourself:

from pydantic_ai_daytona import DaytonaSandbox, DaytonaSandboxSession

async def main():
    async with DaytonaSandboxSession(snapshot='my-snapshot') as session:
        agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[DaytonaSandbox(session=session)])
        await agent.run('Create /workspace/app.py with a hello-world FastAPI app.')
        await agent.run('Now add a /health endpoint to the app you created.')

Configuration reference

Parameter Default Description
snapshot None Snapshot for owned sandboxes (None = Daytona default).
image None Registry image for owned sandboxes (mutually exclusive with snapshot).
sandbox_id None Attach to an existing sandbox instead of creating one.
session None An entered DaytonaSandboxSession you own.
env None Variables applied to every command (owned or attached), also at creation when owned. For injected sessions, configure the session's own env.
workdir None Working directory for commands and relative file paths.
labels None Labels attached to owned sandboxes (cost attribution, filtering).
os_user None OS user commands run as in owned sandboxes.
ephemeral None Delete an owned sandbox as soon as it stops.
network_block_all None Block all outbound network access from owned sandboxes.
network_allow_list None Comma-separated CIDRs owned sandboxes may reach.
domain_allow_list None Comma-separated domains owned sandboxes may reach.
auto_stop_interval None Minutes of inactivity before Daytona stops an owned sandbox.
auto_delete_interval None Minutes after stopping before Daytona deletes an owned sandbox (0 = immediately, -1 = never).
api_key None Daytona API key (falls back to DAYTONA_API_KEY).
api_url None Daytona API URL (falls back to DAYTONA_API_URL).
target None Daytona target region (falls back to DAYTONA_TARGET).
default_command_timeout 60.0 Seconds a command may run when the model omits timeout_seconds.
max_command_timeout 300 Hard ceiling in seconds for any single command.
max_output_bytes 51200 Byte cap per command stream (cut before transfer, even on timeout) or file read. Labels/truncation markers are additional.
max_output_lines 2000 Line cap per command output or file read.
max_read_bytes 5242880 Largest file read_file will read whole.
instructions None Override the system-prompt instructions ('' disables them).

Development

pip install -e ".[dev]"
pytest                          # unit tests (offline)
pytest tests/integration_tests  # live tests (needs DAYTONA_API_KEY)
ruff check .
mypy pydantic_ai_daytona

License

Apache-2.0

Metadata

Release files for pydantic-ai-daytona 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pydantic-ai-daytona 0.2.1
File Size Uploaded Provenance Actions
pydantic_ai_daytona-0.2.1.tar.gz 27.7 kB With provenance Details for pydantic_ai_daytona-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pydantic-ai-daytona 0.2.1
File Interpreter ABI Platform Actions
pydantic_ai_daytona-0.2.1-py3-none-any.whl Python 3 none any Details for pydantic_ai_daytona-0.2.1-py3-none-any.whl

Total release size: 55.7 kB

Release files / pydantic_ai_daytona-0.2.1.tar.gz

Download URL pydantic_ai_daytona-0.2.1.tar.gz
Size 27.7 kB
Tags Source
SHA-256 checksum
How to use checksums
32044a6bde3f99e98653cd40ef94216944e2c89a2d63b67f26cb527acf5b2069
BLAKE2b-256 checksum
How to use checksums
80cd18115f9e254cd0c8ce1cead2e3a92382a8a94477d1bedd56bbc3d8adb832
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / pydantic_ai_daytona-0.2.1-py3-none-any.whl

Download URL pydantic_ai_daytona-0.2.1-py3-none-any.whl
Size 27.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
23d81a58a50fe6a33a1ec78700b808babe64aba10b681678c5cc48e53a7508b2
BLAKE2b-256 checksum
How to use checksums
f4efde180d721188618b4059f7d32e9ec695885c540d6e4294526b7a1413169f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for pydantic-ai-daytona 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pydantic_ai_daytona-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page