OS Sandbox Connector

The OS Sandbox connector provides Agentcy with the ability to provision and interact with isolated operating system environments. It supports multiple sandbox providers and offers 5 live tools for provisioning, command execution, and file operations.

Authentication

Configuration depends on the sandbox provider. Local sandboxes may not require credentials, while cloud providers need API keys.

{
  "name": "OS Sandbox",
  "source_type": "os",
  "config": {
    "provider": "docker_host",
    "server_url": "unix:///var/run/docker.sock",
    "timeout_secs": 30
  }
}

Variable	Required	Description
provider	Yes	Sandbox provider: local, opensandbox, vercel_sandbox, docker_host, kubernetes
server_url	Depends	Server URL for remote providers
api_key	Depends	API key for cloud providers (OpenSandbox, Vercel)
worker_id	No	Specific worker/node to target
timeout_secs	No	Command execution timeout in seconds (default: 30)

WARNING

The local provider runs commands directly on the host machine. Use docker_host or kubernetes for proper isolation in production.

Live Tools (5)

Tool	Description	Arguments
os_provision_sandbox	Provision a new sandbox environment	image?, cpu?, memory?, env?
os_execute_command	Execute a shell command in a sandbox	sandbox_id, command, timeout?
os_read_file	Read a file from the sandbox filesystem	sandbox_id, path
os_write_file	Write a file to the sandbox filesystem	sandbox_id, path, content
os_terminate_sandbox	Terminate and clean up a sandbox	sandbox_id

Example: Agent Using OS Sandbox Tools

User: "Create a sandbox and test if this Python script works"

Agent: I'll provision a sandbox and run the script.
→ Calls os_provision_sandbox(image: "python:3.12-slim")
→ Returns sandbox_id: "sbx-xyz789"
→ Calls os_write_file(sandbox_id: "sbx-xyz789", path: "/app/script.py", content: "...")
→ Calls os_execute_command(sandbox_id: "sbx-xyz789", command: "python /app/script.py")
→ Returns: "Script executed successfully. Output: ..."

User: "Clean up the sandbox"

Agent: I'll terminate it.
→ Calls os_terminate_sandbox(sandbox_id: "sbx-xyz789")
→ Returns: "Sandbox sbx-xyz789 terminated."

ETL Ingestion

This connector does not support ETL ingestion. All tools operate as live interactions with sandbox environments.

Configuration Reference

{
  "name": "OS Sandbox",
  "source_type": "os",
  "config": {
    "provider": "docker_host",
    "server_url": "unix:///var/run/docker.sock",
    "api_key": null,
    "worker_id": null,
    "timeout_secs": 30
  }
}

Field	Type	Default	Description
provider	string	required	Sandbox provider
server_url	string	--	Server URL for remote providers
api_key	string	--	API key for cloud providers
worker_id	string	--	Specific worker/node to target
timeout_secs	number	30	Command execution timeout in seconds

Troubleshooting

Error	Cause	Fix
Connection refused	Docker daemon or remote server unreachable	Verify server_url and that the service is running
Permission denied	Insufficient permissions for Docker socket	Add the user to the docker group or adjust socket permissions
Image not found	Requested container image does not exist	Pull the image first or use a valid image name
Sandbox not found	Sandbox was already terminated or expired	Provision a new sandbox
Command timeout	Command exceeded timeout_secs	Increase timeout_secs or optimize the command
Resource limit exceeded	Sandbox hit CPU or memory limits	Provision with higher cpu or memory values