kernelbox 0.1.2

Python API reference

KernelBox exposes four lightweight functions that cover the full agentic kernel lifecycle:

from kernelbox import get_or_create, execute, execute_with_retry, destroy

get_or_create(name)

Returns a live named kernel, creating it if it doesn't exist yet.

kernel = get_or_create("data-pipeline")

execute(kernel, code, *, language, timeout)

Runs code and returns an ExecutionResult.

result = execute(kernel, "import pandas as pd\ndf = pd.DataFrame({'a': [1,2,3]})")

result.status        # "success" | "error" | "timeout"
result.output        # stdout as string
result.stderr        # stderr as string
result.return_value  # last expression value as string
result.duration_ms   # wall-clock time in milliseconds
result.truncated     # True if output was cut at KERNELBOX_OUTPUT_CHAR_LIMIT

Run a bash command in the same session:

result = execute(kernel, "echo $HOME", language="bash")

execute_with_retry(kernel, code, on_error_fn, *, max_attempts, language, timeout)

Self-healing execution — runs code and calls your on_error_fn on failure, letting the agentic AI loop self-correct before giving up.

from kernelbox import execute_with_retry, get_or_create

kernel = get_or_create("agent")

def fix_code(result, attempt):
    # result.error has: .ename, .evalue, .traceback
    # Return new code to retry, or None to retry the same code
    return f"# attempt {attempt}\nx = 41\nx + 1"

result = execute_with_retry(kernel, "x + 1", on_error_fn=fix_code)
result.status        # "success"
result.return_value  # "42"
len(result.attempts) # number of attempts made

destroy(name)

Shuts down the kernel process and removes it from the registry.

destroy("data-pipeline")

CLI reference

kernelbox create --name my-kernel
kernelbox list
kernelbox list --refresh          # re-ping each kernel for live status
kernelbox status --name my-kernel
kernelbox exec --name my-kernel "print(1 + 1)"
kernelbox exec --name my-kernel --bash "echo hello"
kernelbox exec --name my-kernel --timeout 30 "some_long_call()"
kernelbox restart --name my-kernel
kernelbox destroy --name my-kernel
kernelbox wipe                    # destroy ALL registered kernels

All commands output JSON — easy to pipe into jq:

kernelbox exec --name demo "2 ** 10" | jq .return_value
# "1024"

If you installed KernelBox inside a uv project, prefix commands with uv run kernelbox ...

FastAPI HTTP service

# Development mode (hot-reload)
uvicorn kernelbox.server.app:app --port 8080 --reload

# Or via uv
uv run fastapi dev --port 8080

Docker (recommended for production)

docker-compose up --build -d   # API at http://localhost:8080
docker-compose down

Runs as a non-root user with dropped capabilities and a read-only filesystem.

Configuration

All settings are read from environment variables — no config file needed.

PowerShell:

$env:KERNELBOX_EXECUTION_TIMEOUT = "120"
uv run fastapi dev --port 8080

Bash/zsh:

export KERNELBOX_EXECUTION_TIMEOUT=120
uv run fastapi dev --port 8080

Assumptions & Limitations

Development (from source)

git clone https://github.com/VinayChaudhari1996/KernelBox.git
cd KernelBox

# Bootstrap: installs uv, creates .venv, syncs dev deps
python scripts/bootstrap.py

# Or manually if uv is already installed
uv venv && uv sync --extra dev

uv run pytest              # test suite
uv run ruff check .        # lint
uv run ruff format .       # format
uv run zensical serve      # docs at http://127.0.0.1:8000
uv run fastapi dev --port 8080  # API at http://127.0.0.1:8080

See the Development Guide for architecture details and contribution workflow.