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.

terminal
$ 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.

Full API reference

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

LevelMechanismUse when
processchroot and cgroupsLow-trust internal code, most throughput
microvmFirecracker per tenantMany tenants, strong isolation
dedicatedOne VM per executionThe highest security needs

Security modes, AKERNL_SECURITY_MODE

ModeNetworkFilesystemPackages
restrictedBlockedRead-only except /tmpBlocked
standardOutbound onlyWritable workspaceAllowed
fullUnrestrictedUnrestrictedAllowed

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
example.py
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.

Configuration, architecture and SDK reference

$ pip install "akernl[serve] @ git+https://github.com/cottus-ai/akernl"
configuration, with defaults
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

Runtime infrastructure for AI should be open and self-hostable.

akernl is MIT licensed. Read the code, run it on your hardware, and send a pull request.