dokapy 0.1.1

Self-hosted. Pluggable. Agent-ready.

Secure, isolated sandboxes for AI Agents — without the cloud dependency.

What is doka?

doka gives AI Agents a safe place to run code. It provides a programmable, isolated execution environment where developers can run commands, move files, and control resources — without being locked into any Agent framework or cloud provider.

Runs entirely on your own infrastructure. No API key. No usage limit. No data leaving your machine.

Quick Start

1. Install

pip install dokapy

2. Start a runtime backend

The default runtime is docker. Make sure Docker Desktop (or Docker Engine) is running, or choose a different runtime — see Pluggable runtime backends.

3. Run your first sandbox

from doka import Sandbox

with Sandbox() as sandbox:
    result = sandbox.commands.run('echo "Hello from Doka!"')
    print(result.stdout)  # Hello from Doka!

4. Run an Agent script inside the sandbox

from doka import Sandbox

agent_code = """
print('Agent started')
print('Agent finished')
"""

with Sandbox() as sandbox:
    sandbox.files.write("/tmp/agent.py", agent_code)
    result = sandbox.commands.run("python /tmp/agent.py")
    print(result.stdout)

Core Features

Command-first — works with any Agent framework

doka does not try to standardize how Agents start. LangChain, AutoGen, CrewAI, custom scripts, compiled binaries — bring your own Agent, run it with a command.

with Sandbox() as sandbox:
    sandbox.files.write("/workspace/main.py", agent_code)
    result = sandbox.commands.run("python /workspace/main.py")
    output = sandbox.files.read("/workspace/output.json")

File I/O

with Sandbox() as sandbox:
    sandbox.files.write("/tmp/input.txt", "hello")
    sandbox.commands.run("cat /tmp/input.txt > /tmp/output.txt")
    output = sandbox.files.read("/tmp/output.txt")

Streaming output for long-running processes

process = sandbox.commands.run("python -u agent.py", background=True)

for chunk in process.stdout.stream():
    print(chunk, end="")

exit_code = process.wait()

Resource controls

from doka import Limits, Sandbox

with Sandbox(limits=Limits(cpu=1, memory="512m", network=False)) as sandbox:
    result = sandbox.commands.run("python agent.py")

Pluggable runtime backends

The runtime parameter accepts a URI of the form <driver>[:<variant>].

Runtime support (Runtime Parameter)

Which runtime should I use?

As a rule of thumb: start with docker, upgrade to docker:gvisor when you need stronger isolation, and reach for kata when you want full VM-level security on bare metal.

The API stays the same regardless of which backend you use:

# All four work identically from the caller's perspective
Sandbox(runtime="docker",        image="python:3.11-slim")
Sandbox(runtime="docker:gvisor", image="python:3.11-slim")
Sandbox(runtime="cube",          image="tpl-abc123")
Sandbox(runtime="kata",          image="python:3.11-slim")

Installing CubeSandbox

CubeSandbox runs each sandbox in a KVM MicroVM managed by a local service. See the official repository for installation and setup instructions: 👉 TencentCloud/CubeSandbox

Installing gVisor

gVisor intercepts all syscalls inside a userspace kernel (Sentry), so a container exploit cannot reach the real host kernel directly.

# 1. Add the gVisor apt repository
curl -fsSL https://gvisor.dev/archive.key \
    | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] \
    https://storage.googleapis.com/gvisor/releases release main" \
    | sudo tee /etc/apt/sources.list.d/gvisor.list

# 2. Install and register as a Docker runtime
sudo apt-get update && sudo apt-get install -y runsc
sudo runsc install && sudo systemctl restart docker

# 3. Verify
runsc --version
docker info | grep runsc   # should show "runsc" under Runtimes

Once installed, switch any existing sandbox to gVisor with a one-word change:

# Before
Sandbox(runtime="docker", ...)

# After — stronger isolation, identical API
Sandbox(runtime="docker:gvisor", ...)

Installing Kata Containers

Kata Containers runs each sandbox inside a KVM MicroVM with a dedicated guest kernel (6.x), providing hardware-enforced VM isolation independent of Docker.

# 1. Download and install Kata static bundle
#    https://github.com/kata-containers/kata-containers/releases
#    Choose: kata-static-<version>-amd64.tar.zst
sudo tar -C / -xf kata-static-*-amd64.tar.zst

# 2. Link the containerd shim into PATH
sudo ln -sf /opt/kata/bin/containerd-shim-kata-v2 /usr/local/bin/

# 3. Install nerdctl (Docker-compatible CLI for containerd)
#    https://github.com/containerd/nerdctl/releases  (non-full build, ~20 MB)
sudo tar -C /usr/local/bin -xzf nerdctl-*-linux-amd64.tar.gz nerdctl

# 4. Install CNI network plugins (Linux amd64 version)
#    https://github.com/containernetworking/plugins/releases
sudo mkdir -p /opt/cni/bin
sudo tar -C /opt/cni/bin -xzf cni-plugins-linux-amd64-*.tgz

# 5. Allow nerdctl to run without a password (nerdctl needs root for system containerd)
echo "$USER ALL=(root) NOPASSWD: /usr/local/bin/nerdctl" \
    | sudo tee /etc/sudoers.d/nerdctl

# 6. Verify
sudo nerdctl run --rm --runtime=io.containerd.kata.v2 python:3.11-slim uname -r
# Expected output: 6.x.x  (Kata guest kernel, not the host kernel)

API Reference

Sandbox(runtime="docker", limits=None, image=None)

Creates an isolated sandbox environment.

Recommended usage:

with Sandbox() as sandbox:
    result = sandbox.commands.run("python --version")

Manual lifecycle:

sandbox = Sandbox().start()
try:
    result = sandbox.commands.run("python --version")
finally:
    sandbox.close()

sandbox.commands.run(command, background=False, env=None, workdir=None)

Executes a command inside the sandbox.

Blocking mode returns CommandResult:

result = sandbox.commands.run("python --version")
print(result.stdout)
print(result.stderr)
print(result.exit_code)

Background mode returns Process:

process = sandbox.commands.run("python long_running_agent.py", background=True)

for chunk in process.stdout.stream():
    print(chunk)

exit_code = process.wait()

sandbox.files

Simple file operations inside the sandbox.

sandbox.files.write("/tmp/input.txt", "hello")
exists = sandbox.files.exists("/tmp/input.txt")
content = sandbox.files.read("/tmp/input.txt")

Limits

Resource constraints for the sandbox.

Why doka?

doka is for teams and developers who want a self-hosted sandbox without the overhead of a cloud service:

• No API key. Runs on your machine or your server.
• No usage limits. Run as many sandboxes as your hardware allows.
• No lock-in. Swap the isolation backend as your security requirements grow.
• No framework assumptions. Works with any Agent, any stack, any language.