runebox (Python SDK for Rune Box)

A dependency-light Python client and agent-framework adapters for Rune Box, the open-source governance harness for AI agents (formerly Runeward Sandbox). Install it as runee-box and import it as runebox. Put policy, human approvals, isolated Citadels, Rationing, and signed Chronicles around an existing agent without replacing its model or framework.

The core client uses only the Python standard library (urllib). The LangChain, CrewAI, LlamaIndex, OpenAI Agents SDK, and Strands helpers are optional extras and are imported lazily, so the base client works with nothing else installed.

Install

pip install runee-box                    # core client only (no third-party deps)
pip install "runee-box[langchain]"       # + LangChain tools
pip install "runee-box[crewai]"          # + CrewAI tools
pip install "runee-box[llamaindex]"      # + LlamaIndex tools
pip install "runee-box[openai-agents]"   # + OpenAI Agents SDK tools
pip install "runee-box[strands]"         # + Strands Agents SDK tools

During local development from this directory:

pip install -e .

Quick start

Start the control plane first (runebox serve, default http://localhost:8080), then:

from runebox import RuneboxClient, RuneboxDenied, RuneboxApprovalRequired

rw = RuneboxClient("http://localhost:8080")  # uses RUNEBOX_API_TOKEN when set

sbx = rw.create_sandbox("dev")          # -> {"id": "sbx_...", "backend": "docker", ...}
sid = sbx["id"]

result = rw.shell(sid, ["python3", "--version"])
print(result["stdout"])                 # "Python 3.11.2\n"

rw.write_file(sid, "main.py", "print(2 + 2)")
print(rw.python(sid, "exec(open('/workspace/main.py').read())")["stdout"])  # "4\n"

rw.kill_sandbox(sid)                    # always tear down when done

Use allow_insecure=True (or RUNEBOX_ALLOW_INSECURE_HTTP=1) only when you must call a non-loopback http:// control-plane endpoint.

Handling governance verdicts

The two governance outcomes are raised as typed exceptions. Handle them explicitly — a denial must not be blindly retried, and an approval gate must pause for a human:

try:
    rw.shell(sid, ["rm", "-rf", "/"])
except RuneboxDenied as e:
    print("blocked by policy:", e.reason)     # do NOT retry the same action

try:
    rw.write_file(sid, "/etc/hosts", "127.0.0.1 example")
except RuneboxApprovalRequired as e:
    print("needs a human:", e.approval_id)     # pause; ask an operator to approve/deny

Refusals and request ids

When the server proves a call never ran, its body carries a standard refusal object. The client parses it into a Refusal and, for refusals that are not policy, authorization or approval outcomes (bad request, unknown resource, session_busy, version_conflict, rate limits, budgets, an unmet isolation floor), raises RefusedError. Every error, including RuneboxDenied, RuneboxAuthorizationError and RuneboxApprovalRequired, exposes request_id (the server's X-Request-Id) and refusal:

from runebox import RefusedError, RuneboxError

try:
    rw.agent_turn(session_id, ["claude", "-p", "next step"])
except RefusedError as e:
    print(e.reason, e.retryable, e.message, e.request_id)  # e.g. "request", False, ...
    if e.retryable:
        ...  # safe to send the identical request again later
except RuneboxError as e:
    print("failed; quote this id to the operator:", e.request_id)

rw.last_request_id holds the id of the most recent response.

Isolation

Citadel views carry isolation (process, container, kernel or vm: the tier the sandbox actually runs behind), isolation_evidence (which backend reported it and, on get_sandbox, the policy's floor and whether it is met) and, for policies run under the in-sandbox supervisor, enforcement (Landlock, seccomp, no_new_privs, uid/gid, dropped capabilities).

Workspaces, agent turns, schedules and shared memory

fork = rw.fork_citadel(sid)                     # independent copy of the workspace
rw.sleep_citadel(sid); rw.wake_citadel(sid)     # persistent workspaces only
print(rw.workspace_status(sid)["state"])

sess = rw.start_agent_session(sid, ["claude", "-p", "fix the tests"])
rw.agent_turn(sess["id"], ["claude", "-p", "now update the docs"])
rw.cancel_agent_turn(sess["id"])                # does not rewind workspace changes

rw.create_schedule(["claude", "-p"], citadel=sid, every="1h",
                   prompt="triage new issues", precheck=["test", "-f", "NEW"])
for s in rw.list_schedules(citadel=sid):
    rw.run_schedule(s["id"])

rw.put_memory(cohort_id, "deploy/notes", "staging uses blue/green", tags=["ops"])
hits = rw.search_memory(cohort_id, "staging", tags=["ops"])
claimed = rw.claim_task(cohort_id, "agent-a", context=True)  # notes, brief, memory

Approvals inbox

for a in rw.list_approvals():
    print(a["id"], a["tool"], a["action"], a["reason"])

rw.approve("apr_31c")   # or rw.deny("apr_31c")

Chronicle (audit ledger)

events = rw.audit(sid)          # this Citadel's Chronicle events
assert rw.verify_audit()        # verify the tamper-evident hash chain

Client method surface

LangChain

from runebox import RuneboxClient
from runebox.langchain_tools import make_runebox_tools

tools = make_runebox_tools(RuneboxClient("http://localhost:8080"))
# Pass `tools` to any LangChain agent / AgentExecutor.

The Python framework tools use the same stable concept names as MCP, including runebox_create_citadel, runebox_kill_citadel, and runebox_list_conclave. Governance verdicts are returned as descriptive strings so the agent can reason about a denial or an approval gate.

CrewAI

from runebox import RuneboxClient
from runebox.crewai_tools import make_runebox_tools

tools = make_runebox_tools(RuneboxClient("http://localhost:8080"))
# Attach `tools` to a crewai.Agent(tools=tools, ...).

LlamaIndex

from runebox import RuneboxClient
from runebox.llamaindex_tools import make_runebox_tools

tools = make_runebox_tools(RuneboxClient("http://localhost:8080"))
# Pass `tools` to a FunctionAgent / ReActAgent / AgentRunner.

Returns llama_index.core.tools.FunctionTool instances; the tool schema is derived from each function's type hints and docstring.

OpenAI Agents SDK

from agents import Agent, Runner
from runebox import RuneboxClient
from runebox.openai_agents_tools import make_runebox_tools

tools = make_runebox_tools(RuneboxClient("http://localhost:8080"))
agent = Agent(name="builder", instructions="Use the sandbox tools.", tools=tools)
result = Runner.run_sync(agent, "Create a dev sandbox, run `node --version`, then tear it down.")

Returns @function_tool-built tools; the SDK derives each schema from the function's type hints and docstring.

Strands Agents SDK

from strands import Agent
from runebox import RuneboxClient
from runebox.strands_tools import make_runebox_tools

tools = make_runebox_tools(RuneboxClient("http://localhost:8080"))
agent = Agent(tools=tools)
agent("Create a dev sandbox, run `node --version`, then tear it down.")

Returns @tool-decorated functions; Strands derives each schema from the function's type hints and docstring.

Notes

• deny is a policy decision, not a transient error. Don't retry the same action; pick a different, allowed approach.
• require-approval is a hard pause. Surface the approval_id to a human and wait for the outcome.
• Prefer the tightest profile that lets the task succeed.