Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,21 @@ jobs:
- extra: sandbox
sync-args: --extra sandbox
imports: daytona anycode.sandbox.daytona
- extra: sandbox-e2b
sync-args: --extra sandbox-e2b
imports: e2b anycode.sandbox.e2b
- extra: sandbox-modal
sync-args: --extra sandbox-modal
imports: modal anycode.sandbox.modal
- extra: sandbox-runloop
sync-args: --extra sandbox-runloop
imports: runloop_api_client anycode.sandbox.runloop
- extra: sandbox-vercel
sync-args: --extra sandbox-vercel
imports: vercel anycode.sandbox.vercel
- extra: sandbox-langsmith
sync-args: --extra sandbox-langsmith
imports: langsmith anycode.sandbox.langsmith
- extra: all
sync-args: --extra all
imports: anycode
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- **Expanded sandbox provider catalog** - E2B, Modal, Runloop, Vercel Sandbox, and LangSmith backends now implement the `SandboxProvider` protocol alongside Daytona, each behind its own install extra (`sandbox-e2b`, `sandbox-modal`, `sandbox-runloop`, `sandbox-vercel`, `sandbox-langsmith`) with lazy SDK imports, honest capability reports, evidence digests, and fail-closed handling of unsupported network modes, snapshot restores, and secret schemes. A new `create_sandbox_provider(name)` factory builds any backend by name.
- **Robust Ollama integration** - the Ollama adapter now supports thinking (`reasoning_effort`/`thinking_budget_tokens` map to the native `think` parameter, with `ThinkingBlock` content and `thinking` stream events), structured outputs via `chat(..., response_format=...)` translated to Ollama's `format`, sampling options (`max_tokens` → `num_predict`, plus a `default_options` passthrough for `seed`, `top_p`, `num_ctx`, and friends), `keep_alive`, and ollama.com cloud authentication through `OLLAMA_API_KEY` or `api_key=`.

### Changed

- **Provider-prefixed sandbox secrets** - `SandboxSpec.secret_references` now accepts any `<provider>:<name>` reference instead of only `daytona:`; each backend validates its own prefix at create time and returns `sandbox_secret_reference_invalid` for foreign prefixes. Existing `daytona:` references keep working unchanged.

### Fixed

- **Ollama image input and error reporting** - image blocks are now sent as the native base64 `images` array (previously an unsupported `image_url` shape the server ignored), mid-stream NDJSON error objects surface as terminal `error` stream events instead of a silently truncated answer, `done_reason: "length"` maps to `stop_reason="max_tokens"`, and a `404` names the missing model with the exact `ollama pull` command.
Expand Down
15 changes: 15 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,21 @@ cli = [
sandbox = [
"daytona>=0.197,<1",
]
sandbox-e2b = [
"e2b>=1.0",
]
sandbox-modal = [
"modal>=1.0",
]
sandbox-runloop = [
"runloop-api-client>=0.30",
]
sandbox-vercel = [
"vercel>=0.1,<1",
]
sandbox-langsmith = [
"langsmith[sandbox]>=0.4",
]
all = [
"anthropic>=0.40",
"openai>=1.50",
Expand Down
6 changes: 6 additions & 0 deletions site_docs/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,12 @@ Extras are additive — combine any of them in a single bracketed list, and inst
| `azure` | Azure OpenAI provider support |
| `tokens` | Token counting through `tiktoken` |
| `providers` | All built-in provider SDKs |
| `sandbox` | Daytona sandbox provider support |
| `sandbox-e2b` | E2B sandbox provider support |
| `sandbox-modal` | Modal sandbox provider support |
| `sandbox-runloop` | Runloop sandbox provider support |
| `sandbox-vercel` | Vercel Sandbox provider support (beta SDK) |
| `sandbox-langsmith` | LangSmith sandbox provider support |
| `all` | Every optional provider and framework integration |

!!! note "Install only what the workload uses"
Expand Down
34 changes: 29 additions & 5 deletions site_docs/guides/sandbox-providers.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,44 @@
---
title: "Run AnyCode Work in Sandbox Providers"
description: Configure Daytona or companion sandboxes for AnyCode with identity, network policy, secret references, streamed commands, files, cancellation, and evidence.
keywords: AnyCode sandbox, Daytona Python sandbox, AI agent code execution, policy sandbox provider, isolated agent tools
description: Run AnyCode work in Daytona, E2B, Modal, Runloop, Vercel, or LangSmith sandboxes behind one protocol with network policy, secret references, and evidence.
keywords: AnyCode sandbox, Daytona E2B Modal Runloop Vercel LangSmith sandbox, AI agent code execution, policy sandbox provider, isolated agent tools
---

# Run work through sandbox providers

The `SandboxProvider` protocol gives AnyCode one explicit boundary for remote execution, files, streaming, cancellation, cleanup, health, and evidence. Use `DaytonaSandboxProvider` for the maintained Daytona SDK or `CompanionSandboxAdapter` for a separately deployed sandbox service. Wrap either provider with `PolicySandboxProvider` when every operation needs an external authorization decision.
The `SandboxProvider` protocol gives AnyCode one explicit boundary for remote execution, files, streaming, cancellation, cleanup, health, and evidence. Six remote backends implement it — Daytona, E2B, Modal, Runloop, Vercel Sandbox, and LangSmith — plus `CompanionSandboxAdapter` for a separately deployed sandbox service. Wrap any provider with `PolicySandboxProvider` when every operation needs an external authorization decision.

## Choose a provider

Each backend ships behind its own install extra, and `create_sandbox_provider(name)` builds any of them without importing the SDK until first use:

```python
from anycode import create_sandbox_provider

provider = create_sandbox_provider("e2b") # or daytona, modal, runloop, vercel, langsmith
print(provider.capabilities())
```

| Provider | Extra | Isolation | Snapshots | Live streaming | Network policy | Secret references |
| --- | --- | --- | --- | --- | --- | --- |
| `daytona` | `sandbox` | remote | no | yes | none / allowlist | `daytona:<name>` |
| `e2b` | `sandbox-e2b` | microVM | no | buffered | unrestricted only | rejected |
| `modal` | `sandbox-modal` | container (gVisor) | yes | buffered | none / CIDR allowlist | `modal:<name>` |
| `runloop` | `sandbox-runloop` | VM | yes | buffered | unrestricted only | rejected |
| `vercel` | `sandbox-vercel` | microVM | no | buffered | unrestricted only | rejected |
| `langsmith` | `sandbox-langsmith` | microVM | no | buffered | unrestricted only | rejected |

Every backend fails closed: when a spec requests a network mode, snapshot restore, or secret scheme the provider cannot enforce, `create()` returns a typed error (`sandbox_network_policy_unsupported`, `sandbox_snapshot_unsupported`, `sandbox_secrets_unsupported`, or `sandbox_secret_reference_invalid`) instead of silently granting more than requested. "Buffered" streaming satisfies the streaming contract but delivers output after the command completes. Check `provider.capabilities()` — including its `limitations` tuple — before trusting a workload to a backend.

Credentials always stay in each SDK's own configuration (`E2B_API_KEY`, Modal tokens, `RUNLOOP_API_KEY`, `VERCEL_TOKEN`/`VERCEL_OIDC_TOKEN` with team and project ids, `LANGSMITH_API_KEY`). Do not place credentials in `SandboxSpec`, a command environment, labels, logs, or durable run data.

## Install the Daytona integration

```bash
uv add "anycode-py[sandbox]"
```

Configure Daytona credentials through the SDK's supported host configuration. Do not place credentials in `SandboxSpec`, a command environment, labels, logs, or durable run data.
Configure Daytona credentials through the SDK's supported host configuration.

## Create and use a Daytona sandbox

Expand Down Expand Up @@ -69,7 +93,7 @@ Choose either `image` or `snapshot`, never both. The Daytona adapter currently r
| `network="none"` | No allowlist entries may be supplied |
| `network="allowlist"` | At least one domain or CIDR is required |
| `network="unrestricted"` | The provider may allow unrestricted egress; use only under reviewed host policy |
| `secret_references` | Every value must start with `daytona:` |
| `secret_references` | Every value is a provider-prefixed reference (e.g. `daytona:token-name`); each backend accepts only its own prefix |
| `SandboxCommand.environment` | Credential-like variable names are rejected |

The provider and host must enforce the requested network policy. The model validates the request, but that validation is not proof of kernel, container, VM, or network isolation.
Expand Down
14 changes: 13 additions & 1 deletion site_docs/reference/public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -765,14 +765,26 @@ Carry tenant, principal, and delegation context through a run, and enforce an ex

## Sandboxes

Run commands and file operations inside an isolated provider, gated by a capability and network policy. `PolicySandboxProvider` wraps any provider with policy checks; the Daytona and companion providers are concrete backends. See [run work in sandboxes](../guides/sandbox-providers.md).
Run commands and file operations inside an isolated provider, gated by a capability and network policy. `PolicySandboxProvider` wraps any provider with policy checks; Daytona, E2B, Modal, Runloop, Vercel, LangSmith, and companion providers are concrete backends, and `create_sandbox_provider` builds any of them by name. See [run work in sandboxes](../guides/sandbox-providers.md).

::: anycode.sandbox.protocol.SandboxProvider

::: anycode.sandbox.factory.create_sandbox_provider

::: anycode.sandbox.policy.PolicySandboxProvider

::: anycode.sandbox.daytona.DaytonaSandboxProvider

::: anycode.sandbox.e2b.E2BSandboxProvider

::: anycode.sandbox.modal.ModalSandboxProvider

::: anycode.sandbox.runloop.RunloopSandboxProvider

::: anycode.sandbox.vercel.VercelSandboxProvider

::: anycode.sandbox.langsmith.LangSmithSandboxProvider

::: anycode.sandbox.companion.CompanionSandboxAdapter

::: anycode.sandbox.models.SandboxSpec
Expand Down
12 changes: 12 additions & 0 deletions src/anycode/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -192,11 +192,17 @@
from anycode.sandbox import (
CompanionSandboxAdapter,
DaytonaSandboxProvider,
E2BSandboxProvider,
LangSmithSandboxProvider,
ModalSandboxProvider,
PolicySandboxProvider,
RunloopSandboxProvider,
SandboxCapabilities,
SandboxCommand,
SandboxProvider,
SandboxSpec,
VercelSandboxProvider,
create_sandbox_provider,
)
from anycode.schedule.scheduler import RunScheduler, SweepReport, sweep_once
from anycode.schedule.tasks import ScheduledTask, ScheduledTaskResult, run_scheduled_task
Expand Down Expand Up @@ -606,11 +612,17 @@
# Sandboxes
"CompanionSandboxAdapter",
"DaytonaSandboxProvider",
"E2BSandboxProvider",
"LangSmithSandboxProvider",
"ModalSandboxProvider",
"PolicySandboxProvider",
"RunloopSandboxProvider",
"SandboxCapabilities",
"SandboxCommand",
"SandboxProvider",
"SandboxSpec",
"VercelSandboxProvider",
"create_sandbox_provider",
# Managed hosting
"A2A_AGENT_CARD_PATH",
"A2AAgentCard",
Expand Down
13 changes: 13 additions & 0 deletions src/anycode/sandbox/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

from anycode.sandbox.companion import CompanionSandboxAdapter, CompanionSandboxClient
from anycode.sandbox.daytona import DaytonaSandboxProvider
from anycode.sandbox.e2b import E2BSandboxProvider
from anycode.sandbox.factory import SANDBOX_PROVIDER_EXTRAS, create_sandbox_provider
from anycode.sandbox.langsmith import LangSmithSandboxProvider
from anycode.sandbox.modal import ModalSandboxProvider
from anycode.sandbox.models import (
SANDBOX_CONTRACT_VERSION,
SandboxActionResult,
Expand All @@ -18,13 +22,20 @@
)
from anycode.sandbox.policy import PolicySandboxProvider
from anycode.sandbox.protocol import SandboxProvider
from anycode.sandbox.runloop import RunloopSandboxProvider
from anycode.sandbox.vercel import VercelSandboxProvider

__all__ = [
"SANDBOX_CONTRACT_VERSION",
"SANDBOX_PROVIDER_EXTRAS",
"CompanionSandboxAdapter",
"CompanionSandboxClient",
"DaytonaSandboxProvider",
"E2BSandboxProvider",
"LangSmithSandboxProvider",
"ModalSandboxProvider",
"PolicySandboxProvider",
"RunloopSandboxProvider",
"SandboxActionResult",
"SandboxCapabilities",
"SandboxCommand",
Expand All @@ -37,4 +48,6 @@
"SandboxOutputChunk",
"SandboxProvider",
"SandboxSpec",
"VercelSandboxProvider",
"create_sandbox_provider",
]
110 changes: 110 additions & 0 deletions src/anycode/sandbox/_base.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
"""Shared scaffolding for remote sandbox provider adapters."""

from __future__ import annotations

import inspect
import shlex
from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable
from typing import Any

from anycode.contracts.models import ContractError
from anycode.sandbox.models import SandboxCommand, SandboxCommandResult, SandboxOutputChunk, SandboxSpec


async def call_maybe_async(fn: Any, *args: Any, **kwargs: Any) -> Any:
"""Invoke an SDK callable that may be sync, async, or expose an ``.aio`` twin."""
aio = getattr(fn, "aio", None)
target = aio if callable(aio) else fn
result = target(*args, **kwargs)
if inspect.isawaitable(result):
return await result
return result


async def read_streamish(value: Any) -> str:
"""Normalize SDK output shapes (str, bytes, callable, or object with read())."""
if callable(value):
value = await call_maybe_async(value)
reader = getattr(value, "read", None)
if callable(reader):
value = await call_maybe_async(reader)
if value is None:
return ""
if isinstance(value, bytes | bytearray):
return bytes(value).decode("utf-8", errors="replace")
return str(value)


def to_bytes(value: Any) -> bytes:
if value is None:
return b""
if isinstance(value, bytes | bytearray):
return bytes(value)
return str(value).encode("utf-8")


def network_policy_error(provider: str, spec: SandboxSpec, *, supported: tuple[str, ...]) -> ContractError | None:
"""Fail closed when a backend cannot enforce the requested network mode."""
if spec.network in supported:
return None
return ContractError(
code="sandbox_network_policy_unsupported",
message=f"{provider} cannot enforce network='{spec.network}'; supported modes: {', '.join(supported)}",
)


def secrets_unsupported_error(provider: str, spec: SandboxSpec) -> ContractError | None:
if not spec.secret_references:
return None
return ContractError(
code="sandbox_secrets_unsupported",
message=f"{provider} has no managed secret store; configure credentials on the provider side instead",
)


def snapshot_restore_unsupported_error(provider: str, spec: SandboxSpec) -> ContractError | None:
if not spec.snapshot:
return None
return ContractError(
code="sandbox_snapshot_unsupported",
message=f"{provider} cannot create a sandbox from a snapshot reference",
)


def first_guard_error(*guards: ContractError | None) -> ContractError | None:
for guard in guards:
if guard is not None:
return guard
return None


def shell_command(command: SandboxCommand) -> str:
"""Fold cwd and environment into one POSIX shell string for id-based exec APIs."""
parts: list[str] = []
for key, value in command.environment.items():
parts.append(f"export {key}={shlex.quote(value)}")
if command.cwd:
parts.append(f"cd {shlex.quote(command.cwd)}")
parts.append(command.command)
return " && ".join(parts)


def buffered_stream(
execute: Callable[..., Awaitable[SandboxCommandResult]],
handle: Any,
command: SandboxCommand,
) -> AsyncIterable[SandboxOutputChunk]:
"""Satisfy the streaming contract from a buffered execute() implementation."""

async def generate() -> AsyncIterator[SandboxOutputChunk]:
result = await execute(handle, command)
if not result.ok and result.error is not None:
yield SandboxOutputChunk(stream="error", data=result.error.message, sequence=1)
return
sequence = 0
for stream_name, data in (("stdout", result.stdout), ("stderr", result.stderr)):
if data:
sequence += 1
yield SandboxOutputChunk(stream=stream_name, data=data, sequence=sequence) # type: ignore[arg-type]

return generate()
25 changes: 25 additions & 0 deletions src/anycode/sandbox/_secrets.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
"""Shared helpers for provider-prefixed sandbox secret references."""

from __future__ import annotations

from anycode.contracts.models import ContractError
from anycode.sandbox.models import SandboxSpec


def strip_secret_prefix(provider: str, reference: str) -> str:
"""Return the secret name behind ``<provider>:``, rejecting foreign prefixes."""
prefix = f"{provider}:"
if not reference.startswith(prefix):
raise ValueError(f"Secret reference {reference!r} is not scoped to provider {provider!r}; expected the {prefix!r} prefix")
return reference.removeprefix(prefix)


def validate_secret_references(provider: str, spec: SandboxSpec) -> ContractError | None:
"""Reject references scoped to another provider before any sandbox is created."""
for name, reference in spec.secret_references.items():
if not reference.startswith(f"{provider}:"):
return ContractError(
code="sandbox_secret_reference_invalid",
message=f"Secret reference for {name!r} must use the '{provider}:' prefix",
)
return None
6 changes: 5 additions & 1 deletion src/anycode/sandbox/daytona.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@

from anycode.contracts.models import ContractError
from anycode.helpers.uuid7 import uuid7
from anycode.sandbox._secrets import strip_secret_prefix, validate_secret_references
from anycode.sandbox.models import (
SandboxActionResult,
SandboxCapabilities,
Expand Down Expand Up @@ -59,7 +60,7 @@ def _creation_params(self, spec: SandboxSpec) -> Any | None:
},
"public": False,
"ephemeral": not spec.persistent,
"secrets": {name: reference.removeprefix("daytona:") for name, reference in spec.secret_references.items()},
"secrets": {name: strip_secret_prefix("daytona", reference) for name, reference in spec.secret_references.items()},
"network_block_all": spec.network == "none",
"network_allow_list": ",".join(spec.allowed_cidrs) or None,
"domain_allow_list": ",".join(spec.allowed_domains) or None,
Expand All @@ -78,6 +79,9 @@ async def _resolve(self, handle: SandboxHandle) -> Any:
return sandbox

async def create(self, spec: SandboxSpec) -> SandboxCreateResult:
secret_error = validate_secret_references("daytona", spec)
if secret_error is not None:
return SandboxCreateResult(ok=False, error=secret_error)
try:
client = self._client_or_raise()
params = self._creation_params(spec)
Expand Down
Loading