akernl
A self-hosted sandbox API for AI agent code, in Firecracker microVMs.
Run untrusted code (Python, Node.js, shell or Go) in an isolated sandbox with a single HTTP call. It runs on your own machines, so your data stays there.
MIT license · Python · 0.1
One call to a sandbox.
Start the server, send code, read the result. The sandbox keeps its state, so the next call picks up where this one stopped.
$ export AKERNL_ROOT_KEY=my-root-key
$ akernl serve
Listening on 0.0.0.0:8080
$ curl -X POST http://localhost:8080/api/v1/sandboxes \
-H "x-api-key: $AKERNL_ROOT_KEY" \
-H "Content-Type: application/json" \
-d '{"initial_code": "print(2 + 2)", "initial_language": "python"}'
{
"id": "sbx_01jx...",
"state": "active",
"initial_result": {
"status": "success",
"stdout": "4\n",
"exit_code": 0,
"execution_time_ms": 38
}
}
Fast, isolated, and yours.
Most sandboxes for agent code are cloud-only, share the host's kernel through containers, or take seconds to cold-start.
akernl runs each tenant's sandboxes in Firecracker microVMs: isolated by hardware, booting in under 50 ms, with a pool of warm VMs ready to take a request at once. You own the runtime, and no data leaves your infrastructure.
The API
Five endpoints cover a sandbox's life: create it, run code and commands, move files in and out. Every request carries an API key.
POST /api/v1/sandboxes- Create a sandbox, optionally running initial code.
POST …/:id/execute- Run code in the sandbox. State carries over between calls.
POST …/:id/command- Run a shell command.
PUT …/:id/files- Upload a file.
GET …/:id/files- Download a file.
Choose how sealed.
Isolation level sets the boundary between sandboxes. Security mode sets what code inside may reach. Sandboxes start restricted.
Isolation levels, AKERNL_ISOLATION_LEVEL
| Level | Mechanism | Use when |
|---|---|---|
process | chroot and cgroups | Low-trust internal code, most throughput |
microvm | Firecracker per tenant | Many tenants, strong isolation |
dedicated | One VM per execution | The highest security needs |
Security modes, AKERNL_SECURITY_MODE
| Mode | Network | Filesystem | Packages |
|---|---|---|---|
restricted | Blocked | Read-only except /tmp | Blocked |
standard | Outbound only | Writable workspace | Allowed |
full | Unrestricted | Unrestricted | Allowed |
From Python
The client opens a sandbox for the length of a with block, then cleans it up. Upload data, install packages, run code against both.
python- CPython 3.12
nodejs- Node.js 20
shell- Bash
go- Go 1.22
from akernl.sdk import AkernlClient
client = AkernlClient(
base_url="http://localhost:8080",
api_key="sk-...",
)
with client.sandbox() as sb:
result = sb.execute("python", "print('hello')")
print(result.stdout)
sb.upload("/data.csv", b"a,b\n1,2\n")
sb.install("python", ["pandas"])
result = sb.execute(
"python",
"import pandas as pd; print(pd.read_csv('/data.csv'))",
)
print(result.stdout)
Install
akernl installs from GitHub. The serve extra adds the REST API server.
$ pip install "akernl[serve] @ git+https://github.com/cottus-ai/akernl"
AKERNL_HOST=0.0.0.0
AKERNL_PORT=8080
AKERNL_AUTH_REQUIRED=true
AKERNL_ROOT_KEY=<generated if unset>
AKERNL_SECURITY_MODE=restricted
AKERNL_ISOLATION_LEVEL=process
AKERNL_POOL_MIN_IDLE=2
AKERNL_POOL_MAX_SIZE=20
AKERNL_SANDBOX_TTL=900
AKERNL_FIRECRACKER_PATH=/usr/local/bin/firecracker