# pocketdock

[![CI](https://github.com/deftio/pocketdock/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/pocketdock/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pocketdock)](https://pypi.org/project/pocketdock/)
[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/deftio/pocketdock/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-deftio.github.io%2Fpocketdock-blue)](https://deftio.github.io/pocketdock/)
[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD_2--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)

**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

```python
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

```bash
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](https://github.com/deftio/pocketdock/releases).

Requires [Podman](https://podman.io/getting-started/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).

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

## Documentation

Full documentation is available at **[deftio.github.io/pocketdock](https://deftio.github.io/pocketdock/)**.

- [Quickstart](https://deftio.github.io/pocketdock/quickstart/) — install, build, run your first container
- [User Guide](https://deftio.github.io/pocketdock/guide/containers/) — containers, commands, files, sessions, persistence, profiles
- [CLI Reference](https://deftio.github.io/pocketdock/cli/) — all 22 commands with examples
- [API Reference](https://deftio.github.io/pocketdock/reference/api/) — 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

```bash
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.
