kernelbox 0.1.0

A lightweight IPython kernel utility for agents.

kernelbox

kernelbox is a lightweight utility package for managing IPython kernels from agents, scripts, and small tools. It talks directly to kernels through jupyter_client: no notebook server, web server, browser, or daemon process.

Install

This project is set up for uv.

python scripts/bootstrap.py

The bootstrap script detects Windows, macOS, or Linux, installs uv if it is missing, creates .venv with uv venv, and installs project dependencies with uv sync --extra dev.

Python API

from kernelbox import destroy, execute, get_or_create

kernel = get_or_create("data-analysis")
result = execute(kernel, "sum([1, 2, 3])")

print(result.status)
print(result.return_value)

destroy("data-analysis")

Retry API

from kernelbox import execute_with_retry, get_or_create

kernel = get_or_create("repair-loop")

def on_error(result, attempt):
    return "x = 41\nx + 1"

result = execute_with_retry(kernel, "x + 1", on_error_fn=on_error)

on_error_fn receives the structured ExecutionResult and the current attempt number. If it returns a new code string, the retry loop uses that code for the next attempt. If it returns None, the same code is retried.

CLI

The HTTP service uses the official FastAPI CLI.

uv run fastapi dev
uv run fastapi run

Swagger UI is available at http://127.0.0.1:8000/docs, ReDoc at http://127.0.0.1:8000/redoc, and the OpenAPI schema at http://127.0.0.1:8000/openapi.json.

The lower-level kernel management CLI remains available for scripts:

uv run kernelbox create --name my-kernel
uv run kernelbox list
uv run kernelbox exec --name my-kernel "print(1+1)"
uv run kernelbox exec --name my-kernel --bash "echo hello"
uv run kernelbox restart --name my-kernel
uv run kernelbox status --name my-kernel
uv run kernelbox destroy --name my-kernel
uv run kernelbox wipe

Configuration

Settings can be controlled with environment variables.

Variable	Default	Purpose
KERNELBOX_MAX_RETRIES	5	Max retry attempts per execution
KERNELBOX_KERNEL_IDLE_TIMEOUT	1800	Idle timeout in seconds
KERNELBOX_EXECUTION_TIMEOUT	60	Code execution timeout in seconds
KERNELBOX_OUTPUT_CHAR_LIMIT	10000	Truncate stdout/stderr/rich text output
KERNELBOX_STORE_BACKEND	file	file or memory
KERNELBOX_REGISTRY_PATH	.kernelbox/registry.json on Windows, temp dir elsewhere	File registry path
KERNELBOX_RUNTIME_DIR	.kernelbox/runtime on Windows, temp dir elsewhere	Jupyter connection files
KERNELBOX_STARTUP_CODE	unset	Code run after kernel creation
KERNELBOX_KERNEL_TYPE	python3	Kernel name from Jupyter kernelspecs

Development

uv run pytest

The tests are standard unittest tests, so they can also run without installing pytest if the package is on PYTHONPATH.