Sandboxes

L'environnement d'exécution des commandes et des fichiers de l'agent, et la politique réseau d'une sandbox.

Guides : Sandbox, Sandbox Mistral, Sandboxes locales et Réseau.

class Sandbox(
    *,
    network: Network | None = None,
    header_bindings: Sequence[HeaderBinding | GitHubBinding | MistralApiBinding | WorkspaceHeaderBindings] = (),
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

class Sandbox(
    *,
    network: Network | None = None,
    header_bindings: Sequence[HeaderBinding | GitHubBinding | MistralApiBinding | WorkspaceHeaderBindings] = (),
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

Les options communes à toutes les sandboxes : réseau, secrets, hooks et outils accessibles au modèle.

access définit les outils de la sandbox accessibles au modèle : "files" donne accès aux outils de fichiers, "full" ajoute bash et "none" ne donne accès à aucun des deux, tandis que les outils, les hooks et les skills continuent d'utiliser la sandbox. None donne accès à tous les niveaux pris en charge par la sandbox. Chaque type de sandbox déclare dans supported_access le niveau le plus large qu'il prend en charge, et son constructeur refuse tout niveau plus large.

network définit les connexions sortantes que la sandbox peut ouvrir et utilise par défaut Network.none(). header_bindings liste les secrets accessibles à la sandbox sur ces connexions. Chaque type de sandbox déclare dans supported_network et supported_header_bindings les règles qu'il peut appliquer, et son constructeur refuse les autres.

class NoSandbox(*, hooks: Sequence[SandboxHook] = ())

class NoSandbox(*, hooks: Sequence[SandboxHook] = ())

Exécuter sans sandbox.

Basé sur Sandbox.

class BashkitSandbox(
    *,
    instance_id: str | None = None,
    network: Network | None = None,
    block_private_ips: bool = True,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

class BashkitSandbox(
    *,
    instance_id: str | None = None,
    network: Network | None = None,
    block_private_ips: bool = True,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

Une sandbox qui exécute les commandes shell du modèle dans le processus de l'agent, via l'interpréteur bash de Bashkit, sans conteneur ni Python. Par défaut, elle n'a aucun accès réseau.

Une commande sans timeout_seconds dispose de 300 secondes.

Les adresses privées et de bouclage restent bloquées même si network les autorise. Définissez block_private_ips=False pour accéder à un service sur votre machine, par exemple lors de tests locaux.

instance_id sert à nommer les dossiers de la sandbox sur votre machine, dans le dossier temporaire du système, en combinaison avec l'identifiant de chaque session. Une session rouverte avec le même instance_id, par ce processus ou par un nouveau, retrouve ses dossiers. Sans instance_id, les dossiers sont nommés uniquement à partir de la session.

Basé sur Sandbox.

class DangerousLocalSandbox(
    *,
    shell: Literal['bash', 'sh'] | None = None,
    default_exec_timeout_seconds: int | None = None,
    workspace: str | None = None,
    delete_on_cleanup: bool | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

class DangerousLocalSandbox(
    *,
    shell: Literal['bash', 'sh'] | None = None,
    default_exec_timeout_seconds: int | None = None,
    workspace: str | None = None,
    delete_on_cleanup: bool | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

Exécute les commandes directement dans le processus de l'agent, sans isolation.

Il n'y a pas de conteneur : les commandes du modèle s'exécutent sur votre machine avec l'identité de l'utilisateur de ce processus. Utilisez ce type de sandbox uniquement pour le développement local et la CI, jamais en production.

Les commandes accèdent à tous les réseaux accessibles depuis votre machine. Le paramètre network de la sandbox vaut donc toujours Network.all().

workspace désigne le dossier de l'hôte où les commandes s'exécutent et où l'agent lit et écrit les fichiers. Sans ce paramètre, la sandbox crée un nouveau dossier sous ~/.cache/mistral-vibe-harness-local-host/. Un chemin relatif pour workspace est résolu par rapport au dossier de travail du processus de l'agent.

delete_on_cleanup supprime l'espace de travail à la fermeture de la session. Sa valeur par défaut est True si workspace n'est pas défini et False s'il l'est. La sandbox ne supprime donc jamais votre dossier sans votre demande. Le chemin d'un espace de travail à supprimer doit être absolu et ne doit contenir ni votre dossier personnel ni le dossier de travail du processus ; sinon, la session échoue au démarrage.

Basé sur Sandbox.

class LocalDockerSandbox(
    *,
    image: str | None = None,
    supports_background_processes: bool | None = None,
    shell: Literal['bash', 'sh'] | None = None,
    default_exec_timeout_seconds: int | None = None,
    setup_script: str | None = None,
    setup_script_timeout_seconds: int | None = None,
    network: Network | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

class LocalDockerSandbox(
    *,
    image: str | None = None,
    supports_background_processes: bool | None = None,
    shell: Literal['bash', 'sh'] | None = None,
    default_exec_timeout_seconds: int | None = None,
    setup_script: str | None = None,
    setup_script_timeout_seconds: int | None = None,
    network: Network | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

Une sandbox dans un conteneur Docker sur votre machine, pour le développement.

network utilise par défaut Network.none() : le conteneur n'a aucun accès réseau à l'exception du bouclage, et le script de configuration non plus. Network.all() lui donne accès au réseau par défaut de Docker.

default_exec_timeout_seconds (600 par défaut) arrête une commande envoyée sans délai maximal propre, par exemple ctx.sandbox.execute(...) dans un hook de sandbox : la commande et ses processus enfants reçoivent SIGTERM, puis SIGKILL 5 secondes plus tard, et la commande se termine avec le code de sortie 124. L'image doit fournir une commande setsid (util-linux ou BusyBox).

Basé sur Sandbox.

class MistralSandbox(
    *,
    image: str | None = None,
    supports_background_processes: bool | None = None,
    instance_type: str | None = None,
    region: str | None = None,
    name_prefix: str | None = None,
    ttl_seconds: int | None = None,
    idle_timeout_seconds: int | None = None,
    default_exec_timeout_seconds: int | None = None,
    privileged: bool | None = None,
    docker_daemon_enabled: bool | None = None,
    docker_daemon_network_mode: str | None = None,
    enable_light_sleep: bool | None = None,
    setup_script: str | None = None,
    setup_script_timeout_seconds: int | None = None,
    readiness_max_retries: int | None = None,
    readiness_interval_seconds: float | None = None,
    readiness_probe_timeout_seconds: int | None = None,
    wait_ready_timeout_seconds: int | None = None,
    enable_mesh: bool | None = None,
    network: Network | None = None,
    egress: EgressPolicy | None = None,
    header_bindings: Sequence[HeaderBinding | GitHubBinding | MistralApiBinding | WorkspaceHeaderBindings] = (),
    pre_provisioned_sandbox_id: str | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

class MistralSandbox(
    *,
    image: str | None = None,
    supports_background_processes: bool | None = None,
    instance_type: str | None = None,
    region: str | None = None,
    name_prefix: str | None = None,
    ttl_seconds: int | None = None,
    idle_timeout_seconds: int | None = None,
    default_exec_timeout_seconds: int | None = None,
    privileged: bool | None = None,
    docker_daemon_enabled: bool | None = None,
    docker_daemon_network_mode: str | None = None,
    enable_light_sleep: bool | None = None,
    setup_script: str | None = None,
    setup_script_timeout_seconds: int | None = None,
    readiness_max_retries: int | None = None,
    readiness_interval_seconds: float | None = None,
    readiness_probe_timeout_seconds: int | None = None,
    wait_ready_timeout_seconds: int | None = None,
    enable_mesh: bool | None = None,
    network: Network | None = None,
    egress: EgressPolicy | None = None,
    header_bindings: Sequence[HeaderBinding | GitHubBinding | MistralApiBinding | WorkspaceHeaderBindings] = (),
    pre_provisioned_sandbox_id: str | None = None,
    hooks: Sequence[SandboxHook] = (),
    access: Literal['none', 'files', 'full'] | None = None,
)

Une sandbox que Mistral exécute pour chaque session sur Mistral Cloud.

L'utilisateur associé à la clé API doit avoir le rôle cloud_user (Mistral Cloud User). Mistral Cloud filtre le trafic sortant par adresse IP. network accepte donc Network.none() ou Network.all(). egress=EgressPolicy.custom(allow_cidrs=...) autorise l'accès aux adresses listées en complément de Network.none(). Sandbox Proxy prend en charge header_bindings.

Pour toute option omise, à l'exception de supports_background_processes, network, egress, header_bindings, hooks et access, la valeur par défaut est lue dans la variable d'environnement AGENTS_SDK_KOYEB_SANDBOX_<OPTION>, par exemple AGENTS_SDK_KOYEB_SANDBOX_INSTANCE_TYPE.

Basé sur Sandbox.

class SandboxExecutionResult(exit_code: int, stdout: str, stderr: str)

class SandboxExecutionResult(exit_code: int, stdout: str, stderr: str)

Sortie d'une commande exécutée dans la sandbox de la session en cours.

class SandboxHook

class SandboxHook

Code exécuté à la création de la sandbox et à la fermeture de la session.

on_create et on_destroy peuvent déclarer des entrées de session avec des paramètres Annotated[T, agents.Depends()], comme les outils et les hooks.

Sur un agent déployé, on_create et on_destroy s'exécutent dans la boucle de l'agent : utilisez ctx.sandbox pour les commandes et les fichiers, et agents.now() et agents.sleep() pour la gestion du temps.

Les arguments utilisés pour construire une sous-classe sont enregistrés, ce qui permet à un agent déployé de reconstruire le hook de la sandbox avec les mêmes arguments. Ces arguments doivent être des valeurs JSON. Une sous-classe qui définit ses propres méthodes to_unified_state et from_unified_state remplace ce contrat.

def to_unified_state() -> dict[str, JsonValue]

def to_unified_state() -> dict[str, JsonValue]

Renvoie les arguments utilisés pour construire le hook de la sandbox, à partir desquels un agent déployé le reconstruit.

@classmethod
def from_unified_state(state: dict[str, JsonValue]) -> Self

@classmethod
def from_unified_state(state: dict[str, JsonValue]) -> Self

Reconstruit le hook de la sandbox en appelant son constructeur avec les arguments enregistrés.

async def on_create(ctx: SandboxCallbackContext) -> None

async def on_create(ctx: SandboxCallbackContext) -> None

S'exécute une seule fois lorsque la sandbox est prête, avant le démarrage de l'agent. L'implémentation par défaut ne fait rien.

async def on_destroy(ctx: SandboxCallbackContext) -> None

async def on_destroy(ctx: SandboxCallbackContext) -> None

S'exécute une seule fois à la fermeture de la session. L'implémentation par défaut ne fait rien.

class GitIdentity(*, name: str, email: str)

class GitIdentity(*, name: str, email: str)

Définit les paramètres git globaux user.name et user.email de la sandbox à sa création :

agents.pattern.sandbox_hook.GitIdentity(name="Acme Bot", email="bot@acme.com")

agents.pattern.sandbox_hook.GitIdentity(name="Acme Bot", email="bot@acme.com")

DangerousLocalSandbox refuse ce hook : sur votre machine, il écraserait votre fichier ~/.gitconfig.

Basé sur SandboxHook.

class EgressPolicy(
    *,
    mode: Literal['block_all', 'allow_all', 'custom'] = 'block_all',
    allow_cidrs: tuple[str, ...] = (),
)

class EgressPolicy(
    *,
    mode: Literal['block_all', 'allow_all', 'custom'] = 'block_all',
    allow_cidrs: tuple[str, ...] = (),
)

Les adresses IP auxquelles une MistralSandbox peut se connecter, en complément de son network.

Transmettez EgressPolicy.custom(allow_cidrs=...) à MistralSandbox(egress=...), qui accepte uniquement custom(). block_all() et allow_all() décrivent MistralSandbox.egress_policy pour Network.none() et Network.all().

@classmethod
def block_all() -> EgressPolicy

@classmethod
def block_all() -> EgressPolicy

Bloque toutes les connexions sortantes : la politique egress_policy d'une MistralSandbox avec Network.none().

@classmethod
def allow_all() -> EgressPolicy

@classmethod
def allow_all() -> EgressPolicy

Autorise toutes les connexions sortantes : la politique egress_policy d'une MistralSandbox avec Network.all().

@classmethod
def custom(*, allow_cidrs: Sequence[str]) -> EgressPolicy

@classmethod
def custom(*, allow_cidrs: Sequence[str]) -> EgressPolicy

Autorise l'accès aux adresses listées en complément de Network.none().

class Network(*, mode: Literal['none', 'all', 'allow'] = 'none', hosts: tuple[str, ...] = ())

class Network(*, mode: Literal['none', 'all', 'allow'] = 'none', hosts: tuple[str, ...] = ())

Accès sortant réseau d'une sandbox. À construire avec none(), all() ou allow(hosts=...).

@classmethod
def none() -> Self

@classmethod
def none() -> Self

Aucune connexion sortante.

@classmethod
def all() -> Self

@classmethod
def all() -> Self

Toutes les connexions sortantes.

@classmethod
def allow(*, hosts: Sequence[str]) -> Self

@classmethod
def allow(*, hosts: Sequence[str]) -> Self

Uniquement les connexions HTTPS vers les entrées host ou host:port listées. Les caractères génériques ne sont pas acceptés.

def reaches(host: str) -> bool

def reaches(host: str) -> bool

Indique si ce réseau autorise les connexions vers host, une entrée host[:port].

class HeaderBinding(
    *,
    host: str,
    header: str,
    secret_name: str,
    path_prefix: str = '/',
    prefix: str = '',
    suffix: str = '',
)

class HeaderBinding(
    *,
    host: str,
    header: str,
    secret_name: str,
    path_prefix: str = '/',
    prefix: str = '',
    suffix: str = '',
)

Ajoute un secret aux requêtes HTTPS qu'une sandbox envoie à un hôte.

secret_name sélectionne un secret déclaré par Agent(secrets=...). Une experimental.CustomSandbox qui inclut HeaderBinding dans supported_header_bindings l'accepte et ajoute prefix + value + suffix comme header de chaque requête correspondante. Pour une MistralSandbox, un administrateur de l'espace de travail enregistre ces règles dans Sandbox Proxy : transmettez WorkspaceHeaderBindings.

class GitHubBinding(
    *,
    repos: tuple[str, ...] | Literal['all'],
    ttl_seconds: int = 3600,
    host: str = 'github.com',
)

class GitHubBinding(
    *,
    repos: tuple[str, ...] | Literal['all'],
    ttl_seconds: int = 3600,
    host: str = 'github.com',
)

Donne à une sandbox un accès à Git et à l'API GitHub en tant qu'utilisateur de la session.

Sandbox Proxy obtient un token de courte durée pour l'accès GitHub de l'utilisateur, et le git et le gh de la sandbox l'utilisent sans le voir. Il va plus loin qu'une liaison d'en-tête : il configure aussi git et gh, et vérifie chaque requête par rapport à repos. Il ne prend pas de secret_name parce que le token ne provient jamais de Agent(secrets=...). repos liste les noms owner/repository des dépôts auxquels la sandbox peut accéder, ou vaut "all" pour tous les dépôts auxquels l'utilisateur peut accéder. Le token est renouvelé avant l'expiration du délai ttl_seconds.

class MistralApiBinding(*, ttl_seconds: int = 3600)

class MistralApiBinding(*, ttl_seconds: int = 3600)

Donne à une sandbox un accès à l'API Mistral en tant qu'utilisateur de la session.

Sandbox Proxy fournit à la sandbox une MISTRAL_API_KEY que seul le proxy accepte, ainsi que l'URL du proxy via MISTRAL_API_HTTP_PROXY. Les clients qui envoient leurs requêtes à l'API Mistral via ce proxy, comme la CLI agents, agissent en tant qu'utilisateur de la session sans jamais voir de véritable identifiant. L'identifiant est renouvelé avant l'expiration du délai ttl_seconds.

run_as désigne cette identité. "auto", la seule valeur possible, correspond à l'utilisateur de la session ou, lors d'une exécution locale, à l'utilisateur de MISTRAL_API_KEY.

class WorkspaceHeaderBindings()

class WorkspaceHeaderBindings()

Fait transiter une sandbox Mistral par Sandbox Proxy et applique les règles qu'un administrateur d'espace de travail y a enregistrées.

Chaque règle ajoute un secret d'espace de travail aux requêtes HTTPS qui lui correspondent. Les règles et leurs secrets ne figurent pas dans le code de l'agent, et la sandbox ne voit jamais les secrets.