Sandbox Tool

Documentation Index

Fetch the complete documentation index at: https://hastekit.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Sandbox Tool gives your agent the ability to execute bash commands in an isolated environment. Each conversation gets its own sandbox (container or pod) with a persistent workspace. The agent uses the execute_bash_commands tool to run shell commands and receive stdout, stderr, and exit code.

​

Overview

When the Sandbox tool is enabled:

• The agent can call execute_bash_commands with a code parameter (the bash command to run).
• Each conversation session gets a dedicated sandbox (Docker container or Kubernetes pod, depending on deployment).
• A sandbox daemon runs inside the sandbox and handles exec and file operations over HTTP.
• The workspace is rooted at /sandbox/workspace (configurable via SANDBOX_ROOT). Agent data (e.g. skills) is mounted so the agent can read skill files via bash (e.g. cat /sandbox/skills/.../SKILL.md).
• Sandboxes can shut down after an idle timeout; the next tool call will create a new one for the same session.

This tool is required for Skills to be usable at runtime, because skills are read by the agent via execute_bash_commands.

​

Enabling the Sandbox Tool

1. Open your agent in the Agent Builder.
2. Go to the Tools tab.
3. Enable Sandbox (Bash / execute_bash_commands).
4. Optionally set a Docker image for the sandbox container. If not set, the server uses SANDBOX_DEFAULT_IMAGE from the environment.
5. Save your agent.

Sandbox must be enabled at the server level (e.g. SANDBOX_ENABLED=true and a valid sandbox manager). If the sandbox backend is not configured, enabling the tool in the UI will not provide a working sandbox.

​

Tool: execute_bash_commands

The only tool exposed to the LLM is: The agent sends a JSON object with code set to the shell command (e.g. "ls -la", "cat /sandbox/workspace/foo.txt"). Commands are run via /bin/sh -c inside the sandbox, so normal shell syntax (pipes, redirections, etc.) is supported.

​

Response format

The sandbox returns a JSON object with: Timeouts are enforced by the daemon (default 60 seconds). On timeout, the response may indicate failure and the process is killed.

​

How it works

1. Sandbox lifecycle
   When the agent calls execute_bash_commands, the server uses the sandbox Manager to ensure a sandbox exists for the current session (agent + conversation). The manager can be backed by Docker (e.g. for local/dev) or Kubernetes (e.g. in production). It creates a container/pod running the sandbox image and the sandbox daemon.
2. Sandbox daemon
   The daemon listens inside the sandbox (default port 8080). It exposes:
   • Exec: POST /exec/bash and POST /exec/python with a JSON body (command/script, optional workdir, env, timeout). The agent-facing tool currently uses only bash.
   • Files: GET /files/<path>, POST /files/<path>, DELETE /files/<path> for reading, writing, and deleting files under the sandbox root. Paths are validated so they cannot escape the root.
3. Workspace and agent data
   The sandbox root is typically /sandbox/workspace (or SANDBOX_ROOT). Agent-specific data (e.g. skills) is mounted under a path the agent can access (e.g. /sandbox/skills/...), so the agent can run cat /sandbox/skills/<name>/SKILL.md to read skill content.
4. Idle timeout
   The daemon may shut down the process after a period of inactivity (e.g. 30 seconds). The next tool call will trigger creation of a new sandbox for that session; any files only in the previous sandbox’s filesystem are not carried over unless they are on a persistent volume.

​

Configuration

​

Server / environment

• SANDBOX_ENABLED – If set (e.g. true), the server initializes a sandbox manager (Docker or Kubernetes). If unset or disabled, the Sandbox tool is not available.
• SANDBOX_DEFAULT_IMAGE – Default Docker image for sandbox containers/pods (e.g. praveenraj9495/hastekit-ai-sandbox:latest). Must be an image that runs the HasteKit sandbox daemon (e.g. hastekit-ai-sandbox sandbox-daemon).
• SANDBOX_ROOT – (Inside the sandbox container.) Root directory for the workspace and file API; default /sandbox/workspace.
• SANDBOX_PORT – (Inside the sandbox container.) Port the daemon listens on; default 8080.

Kubernetes vs Docker is chosen at server startup (e.g. via config or env) and is not per-agent.

​

Agent / tool config

• Sandbox tool enabled – Turns on the execute_bash_commands tool for that agent.
• docker_image (optional) – Overrides the default sandbox image for that agent. If not set, SANDBOX_DEFAULT_IMAGE is used.

​

Relation to other features

• Skills – Skills are stored under the agent’s sandbox data and mounted into the sandbox. The agent is instructed to use execute_bash_commands to read skill files (e.g. SKILL.md). Therefore, enabling the Sandbox tool is required for skills to work at runtime.
• Provider Code Execution – The provider’s built-in code execution tool (e.g. for short snippets) is separate. The Sandbox tool is HasteKit-managed, session-scoped, and supports full bash and a persistent workspace plus file access.

​

Summary