The self-hosted execution runtime and skills registry for AI agents.
Your agents need a sandbox. Don't build one.
Skillbox gives AI agents a single API to register, discover, and execute sandboxed skill scripts (Python, Node.js, Bash) and receive structured JSON output + file artifacts. Think of it as a package registry — but for agent capabilities. Push skills, version them, let agents browse what's available, and run them in hardened sandboxes. Self-hosted, open source, secure by default.
fromskillboximportClientclient=Client("http://localhost:8080", "sk-your-key")
# Discover what skills are availableforskillinclient.list_skills():
print(f"{skill.name}: {skill.description}")
# Run a skill — structured in, structured outresult=client.run("data-analysis", input={"data": [1, 2, 3, 4, 5]})
print(result.output) # {"row_count": 5, "mean": 3.0, ...}Every AI agent that does useful work needs to execute code. But executing arbitrary code is dangerous. Most teams either skip sandboxing ("we'll fix it later") or build their own broken wrapper. Skillbox is the missing piece:
| Problem | How Skillbox Solves It |
|---|---|
| "We need sandboxing but E2B/Modal are cloud-only" | Self-hosted. Your infrastructure, your data, your rules. |
| "Three teams built three sandbox wrappers" | One runtime. One API. One security review. |
| "Our agents don't know what tools are available" | Skills registry — agents discover, inspect, and choose capabilities like browsing a package index. |
| "We need GDPR/EU AI Act compliance" | Data never leaves your network. MIT license. |
| "Docker is insecure for running untrusted code" | OpenSandbox with 6 layers of hardening enforced by the runtime, not configurable by callers. |
| Skillbox | E2B | Modal | Daytona | |
|---|---|---|---|---|
| Self-hosted | Yes (MIT) | Experimental | No | Limited |
| Skills registry | Yes (SKILL.md) | No | No | No |
| Structured I/O | JSON in → JSON out | Raw stdout | Raw stdout | Raw stdout |
| Agent introspection | list + get_skill | No | No | No |
| LangChain-native | 1:1 tool mapping | Manual | Manual | Manual |
| Network disabled | Always | Optional | No | No |
| Zero-dep SDK | Go + Python | Python | Python | REST only |
| File management | Upload, version, download | Limited | No | No |
| License | MIT | Apache-2.0 | Proprietary | Apache-2.0 |
- Secure by default — OpenSandbox isolation with network disabled, resource limits enforced, image allowlist, timeout enforcement, env var blocking, and API-based lifecycle (no Docker socket). 6 layers, all mandatory.
- Skills registry — Skillbox is a registry for agent capabilities. Push skills like you push packages — versioned, discoverable, introspectable units with YAML metadata + markdown instructions. Agents browse, inspect, and choose the right skill before executing.
- Structured I/O — Skills read JSON input, write JSON output, and produce file artifacts. No stdout parsing.
- LangChain-ready — Skills map 1:1 to LangChain tools.
get_skillreturns descriptions for tool selection. - Self-hosted — Docker Compose with OpenSandbox service (dev), Kubernetes (prod), Helm chart. Air-gapped? Works offline.
- Multi-tenant — API keys scoped to tenants, skills and executions isolated.
- Zero-dep SDKs — Go and Python clients use only the standard library. No dependency conflicts.
- CLI — Push, lint, run, package, and manage skills from the terminal.
- File artifacts — Skills write files, runtime tars them, presigned S3 URL returned.
- File persistence — Files persist across sessions, support versioning, and can be edited after creation via the file management API.
- 12-factor config — All configuration via environment variables.
Prerequisites: Docker and Docker Compose. The compose stack includes the OpenSandbox service for sandbox execution.
# 1. Start the stack (includes OpenSandbox, MinIO, PostgreSQL)
git clone https://github.com/devs-group/skillbox.git &&cd skillbox
docker compose -f deploy/docker/docker-compose.yml up -d
# 2. Create an API key
bash scripts/seed-apikey.sh
export SKILLBOX_API_KEY=sk-... # from the script output# 3. Install the CLI and push a skill
go install github.com/devs-group/skillbox/cmd/skillbox@latest
skillbox skill push examples/skills/data-analysis --server http://localhost:8080
# 4. Run it
skillbox run data-analysis --input '{"data": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}'Or with curl:
curl -s http://localhost:8080/v1/executions \
-H "Authorization: Bearer $SKILLBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"skill": "data-analysis", "input": {"data": [{"name": "Alice", "age": 30}]}}'| jq .Security is enforced by the runtime — not configurable away by callers:
| Control | Implementation | Threat Mitigated |
|---|---|---|
| Network isolation | OpenSandbox NetworkPolicy (defaultAction: deny) | Data exfiltration, SSRF |
| Resource limits | CPU and memory caps sent to OpenSandbox, clamped to server-side maximums | Fork bombs, resource exhaustion |
| Image allowlist | Validated by Skillbox before CreateSandbox call | Supply-chain attack |
| Timeout | Go context cancellation + sandbox TTL | Resource exhaustion |
| Env var blocking | LD_PRELOAD, PYTHONPATH, NODE_OPTIONS, SANDBOX_* filtered before passing | Library injection |
| Sandbox lifecycle | OpenSandbox API (no Docker socket required) | Host escape |
For genuinely untrusted code, gVisor or Kata Containers can be enabled as a Kubernetes RuntimeClass with zero changes to Skillbox.
A skill is a zip archive containing SKILL.md + scripts:
my-skill/
├── SKILL.md # YAML frontmatter + instructions
├── scripts/
│ └── main.py # Entrypoint
└── requirements.txt # Optional: Python deps
---
name: data-analysisversion: "1.0.0"description: Analyze CSV data and produce summary statisticslang: pythontimeout: 60sresources:
memory: 256Micpu: "0.5"
---
# Data Analysis SkillAnalyze data and produce summary statistics with charts.The YAML frontmatter is machine-readable (for SDKs and API). The markdown body is LLM-readable (for agent tool selection). This dual format is what makes Skillbox skills work as LangChain tools out of the box.
See docs/SKILL-SPEC.md for the full specification.
Single file, zero dependencies beyond the Go standard library:
go get github.com/devs-group/skillbox/sdks/goimport skillbox "github.com/devs-group/skillbox/sdks/go"client:=skillbox.New("http://localhost:8080", "sk-your-key",
skillbox.WithTenant("my-team"),
)
// Create a skill from structured fields (no zip packaging needed)skill, err:=client.UpsertSkillFromFields(ctx, skillbox.CreateFromFieldsRequest{
Name: "text-summary",
Description: "Summarize long text into key sentences",
Lang: "python",
Code: "import json, os\ndata = json.loads(os.environ['SANDBOX_INPUT'])\nprint(json.dumps({'summary': data['text'][:100]}))",
})
// Run a skillresult, err:=client.Run(ctx, skillbox.RunRequest{
Skill: "text-summary",
Input: json.RawMessage(`{"text": "Long text here...", "max_sentences": 3}`),
})
ifresult.HasFiles() {
err=client.DownloadFiles(ctx, result, "./output")
}
// File managementfiles, err:=client.ListFiles(ctx, skillbox.FileFilter{ExecutionID: "exec-abc-123"})
err=client.DownloadFile(ctx, files[0].ID, "./output/report.pdf")Single file, zero dependencies beyond the Python standard library:
fromskillboximportClientclient=Client("http://localhost:8080", "sk-your-key", tenant_id="my-team")
result=client.run("text-summary", input={"text": "Long text here...", "max_sentences": 3})
print(result.output) # {"summary": "...", "sentence_count": 2}ifresult.has_files:
client.download_files(result, "./output")
# File managementfiles=client.list_files(execution_id="exec-abc-123")
client.download_file(files[0].id, "./output/report.pdf")Skillbox skills map directly to LangChain tools. Each skill becomes a callable tool that an agent can discover, inspect, and execute:
fromlangchain_anthropicimportChatAnthropicfromlanggraph.prebuiltimportcreate_react_agent# Build tools from all registered skillstools=build_skillbox_toolkit("http://localhost:8080", "sk-your-key")
# Agent sees tools like skillbox_data_analysis, reads their descriptions,# picks the right one, calls it with structured input, gets structured outputagent=create_react_agent(ChatAnthropic(model="claude-sonnet-4-6"), tools)
result=agent.invoke({
"messages": [{"role": "user", "content": "Analyze this data: name,age\nAlice,30\nBob,25"}]
})See the full LangChain integration guide for SkillboxTool, SkillboxToolkit, and custom tool examples.
Agent → REST API → Skill Registry (MinIO) → OpenSandbox Runner → Sandbox (hardened) → Output + Files
↕ ↕
PostgreSQL OpenSandbox API (lifecycle + ExecD)
Every execution: authenticate → load skill → validate image → create hardened sandbox via OpenSandbox → run → collect output + files → cleanup. Stateless API, horizontally scalable behind a load balancer.
See docs/ARCHITECTURE.md for the full deep-dive.
skillbox run <skill> [--input '{}'] [--version latest]
skillbox skill push <dir|zip>
skillbox skill list
skillbox skill lint <dir>
skillbox skill package <dir>
skillbox exec logs <id>
skillbox health
skillbox versiondocker compose -f deploy/docker/docker-compose.yml upkubectl apply -k deploy/k8s/overlays/prodhelm install skillbox deploy/helm/skillbox/Kustomize overlays for dev and prod environments. Includes namespace, RBAC, NetworkPolicy, and Pod Security Standards. OpenSandbox manages container lifecycle directly -- no Docker socket proxy required.
| Method | Path | Description |
|---|---|---|
| POST | /v1/executions | Run a skill |
| GET | /v1/executions/:id | Get execution result |
| GET | /v1/executions/:id/logs | Get execution logs |
| POST | /v1/skills | Upload a skill zip |
| GET | /v1/skills | List skills (with descriptions) |
| GET | /v1/skills/:name/:version | Get skill metadata + instructions |
| DELETE | /v1/skills/:name/:version | Delete a skill |
| POST | /v1/files | Upload a file |
| GET | /v1/files | List files (with pagination) |
| GET | /v1/files/:id | Get file metadata |
| GET | /v1/files/:id/download | Download file content |
| PUT | /v1/files/:id | Update/version a file |
| DELETE | /v1/files/:id | Delete a file |
| GET | /v1/files/:id/versions | List file versions |
| GET | /health | Liveness probe |
| GET | /ready | Readiness probe |
See docs/API.md for the full reference.
| Example | Description |
|---|---|
| examples/skills/data-analysis/ | CSV/JSON statistics with chart artifacts |
| examples/skills/text-summary/ | Extractive text summarization |
| examples/skills/word-counter/ | Word frequency counting |
| examples/curl/ | Step-by-step curl + jq walkthrough |
| examples/python/ | Python integration (stdlib only) |
| examples/agent-integration/ | Full Go agent using the SDK |
| examples/write-your-first-skill/ | Build your first skill (tutorial) |
Run all examples at once:
docker compose -f examples/docker-compose.yml upAll configuration via environment variables (12-factor):
| Variable | Default | Description |
|---|---|---|
SKILLBOX_DB_DSN | required | PostgreSQL connection string |
SKILLBOX_S3_ENDPOINT | required | MinIO/S3 endpoint |
SKILLBOX_S3_ACCESS_KEY | required | S3 access key |
SKILLBOX_S3_SECRET_KEY | required | S3 secret key |
SKILLBOX_OPENSANDBOX_URL | http://localhost:8080 | OpenSandbox API URL |
SKILLBOX_OPENSANDBOX_API_KEY | required | OpenSandbox API key |
SKILLBOX_SANDBOX_EXPIRATION | 5m | Sandbox TTL |
SKILLBOX_IMAGE_ALLOWLIST | python:3.12-slim,... | Allowed Docker images |
SKILLBOX_DEFAULT_TIMEOUT | 120s | Default execution timeout |
SKILLBOX_API_PORT | 8080 | HTTP port |
SKILLBOX_REDIS_URL | (optional) | Redis URL for caching |
We welcome contributions! See CONTRIBUTING.md for development setup, coding guidelines, and how to add new skills.
MIT. See LICENSE.
Built and maintained by devs group · Kreuzlingen, Switzerland