pocketdock

Portable, offline-first container sandboxes for LLM agents and dev workflows.

One Container class. Podman-first, Docker-compatible. Python SDK + CLI. Zero cloud. Zero API keys.

Why pocketdock?

Managed sandbox platforms require API keys, cloud accounts, and an internet connection. Rolling your own container glue means rewriting hundreds of lines of boilerplate every time. pocketdock sits in between: a clean Python SDK that talks directly to your container engine over its Unix socket, works entirely offline, and has zero external dependencies for the core SDK.

Features

• Three execution modes — blocking, streaming, and detached (background) with ring buffer
• File operations — read, write, list, push, and pull files between host and container
• Persistent sessions — long-lived shell sessions with state (cwd, env vars, history)
• Resource limits — memory caps, CPU throttling, per-container isolation
• Port mapping — expose container ports on the host (e.g., ports={8080: 80})
• Container persistence — stop/resume, snapshot to image, volume mounts
• Project management — .pocketdock/ project directories with config, logging, and health checks
• Image profiles — six pre-baked Dockerfiles: minimal-python, minimal-node, minimal-bun, dev, agent, embedded
• Full CLI — 22 commands for container lifecycle, file ops, and project management
• Async-first — sync facade over async core; use either API style
• Callbacks — register handlers for stdout, stderr, and exit events

Quick Example

from pocketdock import create_new_container

with create_new_container() as c:
    result = c.run("echo hello")
    print(result.stdout)  # "hello\n"
    print(result.ok)      # True

Install

pip install pocketdock          # SDK + CLI (includes click, rich)
pip install pocketdock[agent]   # + LLM agent (litellm, python-dotenv)

Single-file downloads (no pip required) are available from GitHub Releases.

Requires Podman (recommended) or Docker.

# Build the minimal-python image (~25MB, <500ms startup)
pocketdock build minimal-python

Documentation

Full documentation is available at deftio.github.io/pocketdock.

• Quickstart — install, build, run your first container
• User Guide — containers, commands, files, sessions, persistence, profiles
• CLI Reference — all 22 commands with examples
• API Reference — full SDK reference

Architecture

User Code / LLM Agent / CLI
        |
        v
  pocketdock SDK
  +--------------------------------------+
  | Container (sync)  -> AsyncContainer  |  facade pattern
  |   +- _socket_client (raw HTTP/Unix)  |
  +- ProjectManager (.pocketdock/)      |
  +- Persistence (resume, snapshot)      |
  +- Sessions (persistent shells)        |
  +--------------------------------------+
        |  raw HTTP over Unix socket
        |  (one connection per operation)
        v
  Podman (rootless) / Docker Engine

Design principles:

• Connection-per-operation — each API call opens its own Unix socket. No pooling.
• Async core, sync facade — AsyncContainer does all real work. Container is a sync wrapper.
• No cached state — always polls live from the engine.
• Minimal dependencies — stdlib-only for the core SDK.

Development

uv sync --dev                    # Install dependencies
uv run pytest                    # Run tests (100% coverage enforced)
uv run ruff check .              # Lint (zero warnings)
uv run mypy --strict python/     # Type checking (strict mode)
uv run mkdocs serve              # Local docs site

License

BSD-2-Clause. Copyright (c) deftio llc.