Sandbox tools

Sandbox tools use a sandbox.Provider from pkg/agents/sandbox. The provider creates and reconnects execution environments; tools run commands and access files. Docker and Kubernetes use the HasteKit sandbox daemon, while E2B and Daytona use their service protocols.

Configure a provider

Import pkg/agents/sandbox/providers/docker, pkg/agents/tools, and github.com/moby/moby/api/types/container:

provider, err := docker.New(docker.Config{
    Profiles: map[string]docker.Profile{
        "analysis": {
            Config: container.Config{Image: "your-registry/sandbox-daemon:tag"},
        },
    },
})
if err != nil { return err }
defer provider.Close()

sandboxTools := []hastekit.Tool{
    tools.NewBashTool(provider, "analysis", nil),
    tools.NewReadFileTool(provider, "analysis", nil),
    tools.NewWriteFileTool(provider, "analysis", nil),
    tools.NewDeleteFileTool(provider, "analysis", nil),
}

Add sandboxTools to AgentConfig.Tools. The second argument is a configured profile name. Supply an image with the sandbox daemon and Bash; the provider does not build it. Keep the provider open until all runs finish.

Choose a backend

Package under `pkg/agents/sandbox/providers`	Environment
`docker`	Docker Engine containers and daemon routing
`k8s`	Kubernetes pods, pod templates, and application-managed storage
`e2b`	E2B templates
`daytona`	Daytona snapshots

hastekitgateway.Config.NewSandboxClient() is a gateway-specific HTTP client implementing the same provider contract. Applications can also implement sandbox.Provider directly.

State and commands

sandbox.Acquire reconnects using the reference saved under sandbox.StateKey in run state, or creates a resource when no reference exists. Tools return state updates that later calls and persisted turns reuse. Approval and middleware run before provisioning. The bash tool executes bash -c with the supplied code. Use its workdir argument for a working directory; cd affects only that invocation. Nonzero exit codes are command results, not transport errors. Separate threads do not automatically share compute, even when they share a session. Concurrent runs of the same session are unsupported. A corrupt reference, scope mismatch, or missing saved resource fails rather than silently provisioning a replacement. Changing creation settings does not reconfigure an existing environment.

Lifecycle

Configure mounts, resource limits, networking, credentials, and cleanup in the provider. A crash before the resource reference is persisted can orphan compute. Command cancellation stops waiting; remote process termination depends on the provider. Do not retry external commands blindly. The SDK repository contains daemon image instructions in deployments/sandbox and backend configuration guides beside each provider. Use approval or middleware for sensitive operations.

Getting started

Core concepts

Models and providers

Tools and capabilities

Multi-agent patterns

Interfaces

Durable execution

Scheduled work

Workflows

Testing and operations

Configure a provider

Choose a backend

State and commands

Lifecycle

​Configure a provider

​Choose a backend

​State and commands

​Lifecycle

Configure a provider

Choose a backend

State and commands

Lifecycle