pocketdock 1.1.0__tar.gz

pocketdock-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --dev --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy --strict python/pocketdock/
+      - run: uv run bandit -r python/pocketdock/ -c pyproject.toml
+      - name: Check license headers
+        run: |
+          find python/pocketdock -name '*.py' | while read f; do
+            head -2 "$f" | grep -q 'SPDX-License-Identifier: BSD-2-Clause' || \
+              (echo "Missing license header: $f" && exit 1)
+          done
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --dev --all-extras --python ${{ matrix.python-version }}
+      - run: systemctl --user start podman.socket
+      - run: podman build -t pocketdock/minimal images/minimal/
+      - name: Run parallel-safe tests
+        run: uv run pytest -n auto --ignore=tests/test_persistence_integration.py
+      - name: Run serial tests (race-prone)
+        run: uv run pytest tests/test_persistence_integration.py --cov-append --cov-fail-under=100
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --dev
+      - run: uv run mkdocs build --strict
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --dev
+      - run: uv run pip-audit

pocketdock-1.1.0/.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --dev
+      - run: uv run mkdocs gh-deploy --force

pocketdock-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pocketdock-1.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Testing / coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# mkdocs
+site/
+
+# pocketdock runtime data
+.pocketdock/
+
+# Environment / secrets
+.env
+.env.*
+
+.claude

pocketdock-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [click, types-click]
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: "1.8.0"
+    hooks:
+      - id: bandit
+        args: [-c, pyproject.toml]
+
+  - repo: https://github.com/mgedmin/check-manifest
+    rev: "0.50"
+    hooks:
+      - id: check-manifest

pocketdock-1.1.0/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.1.0] - 2026-02-11
+
+### Changed
+
+- Renamed project from `pocket-dock` to `pocketdock` — package, imports, CLI command, labels, image tags, project directories, and all references
+- PyPI package name: `pocketdock` (was `pocket-dock`)
+- CLI command: `pocketdock` (was `pocket-dock`)
+- Python import: `import pocketdock` (was `import pocket_dock`)
+- Image tags: `pocketdock/minimal` etc. (was `pocket-dock/minimal`)
+- Project directory: `.pocketdock/` (was `.pocket-dock/`)
+- Config file: `pocketdock.yaml` (was `pocket-dock.yaml`)
+- Container labels: `pocketdock.*` (was `pocket-dock.*`)
+
+## [1.0.1] - 2026-02-11
+
+### Changed
+
+- Rewrote README as a focused landing page with features list, quick example, and docs links
+- Comprehensive docs site with 17 pages: user guide, CLI reference, API reference, concepts
+- GitHub Pages deployment via `mkdocs gh-deploy` workflow
+- Added `navigation.tabs`, `navigation.top`, and `content.tabs.link` theme features to mkdocs
+
+## [1.0.0] - 2026-02-10
+
+### Added
+
+- Four image profiles: `minimal`, `dev`, `agent`, `embedded` — pre-baked Dockerfiles for common use cases
+- `profiles.py` module — `ProfileInfo` dataclass, `resolve_profile()`, `list_profiles()`, `get_dockerfile_path()`
+- `profile` parameter on `create_new_container()` — resolves profile name to image tag automatically
+- `devices` parameter on `create_new_container()` — USB/device passthrough to containers
+- `build_image()`, `save_image()`, `load_image()` socket client methods for image management via engine API
+- CLI `build` command — build profile images from Dockerfiles via socket API
+- CLI `export` command — save images to tar/tar.gz files for air-gap transfer
+- CLI `import` command — load images from tar/tar.gz files
+- CLI `profiles` command — list available profiles (table or `--json`)
+- `--profile` and `--device` options on CLI `create` command
+- Exported `ProfileInfo`, `resolve_profile`, `list_profiles` from `pocketdock` and `pocketdock.async_`
+
+### Changed
+
+- Version bump to 1.0.0 — stable API
+
+## [0.9.0] - 2026-02-10
+
+### Added
+
+- Full CLI with 17 commands: `init`, `list`, `info`, `doctor`, `status`, `logs`, `create`, `run`, `push`, `pull`, `reboot`, `stop`, `resume`, `shutdown`, `snapshot`, `prune`, `shell`
+- `stop_container()` — stop a running container by name without removing it (sync and async)
+- `--json` flag on read commands (`list`, `info`, `doctor`, `status`, `logs`) for machine-readable output
+- `--stream` and `--detach` flags on `run` for streaming and background execution
+- `--yes/-y` flag on destructive commands (`shutdown`, `prune`) to skip confirmation prompts
+- `--socket` global option and `POCKET_DOCK_SOCKET` env var for engine socket override
+- Rich-formatted output: tables for container lists, panels for info/doctor, colored success/error messages
+- `shell` command — interactive shell via engine CLI passthrough (`podman`/`docker exec -it`)
+- Entry point: `pocketdock` (via `pyproject.toml` console script)
+- `click` and `rich` CLI dependencies (optional `[cli]` extra)
+
+## [0.8.0] - 2026-02-10
+
+### Added
+
+- `.pocketdock/` project management — `init_project()`, `find_project_root()`, `get_project_name()`
+- Instance directory lifecycle — `ensure_instance_dir()`, `write_instance_metadata()`, `read_instance_metadata()`, `remove_instance_dir()`, `list_instance_dirs()`
+- `PocketDockConfig` dataclass and `load_config()` with install-level → project-level precedence
+- `pocketdock.yaml` project configuration file with logging and persistence defaults
+- `instance.toml` metadata files per persistent container (container info, resources, provenance)
+- `project` parameter on `create_new_container()` — associates containers with a project
+- `pocketdock.project` and `pocketdock.data-path` labels on persistent containers
+- `list_containers(project=...)` and `prune(project=...)` — filter by project name
+- `destroy_container()` now cleans up the instance directory when `pocketdock.data-path` label is present
+- `InstanceLogger` — auto-logging of `run()` results, session I/O, and detached process output to disk
+- `history.jsonl` command history per instance
+- `doctor()` — cross-references local instance dirs with engine containers to find orphaned containers and stale dirs
+- `DoctorReport` dataclass with `orphaned_containers`, `stale_instance_dirs`, `healthy`
+- `ProjectNotInitialized` exception
+- `PyYAML` and `tomli` (Python < 3.11) added as core dependencies for config/metadata parsing
+- All new functions available as sync (from `pocketdock`) and async (from `pocketdock.async_`)
+
+## [0.7.0] - 2026-02-10
+
+### Added
+
+- `persist=True` parameter for `create_new_container()` — container survives `shutdown()` (stop without remove)
+- `volumes` parameter for `create_new_container()` — mount host directories into the container
+- `container.snapshot(image_name)` — commit container filesystem as a new reusable image
+- `container.persist` property — check if container is persistent
+- `resume_container(name)` — resume a stopped persistent container by name
+- `list_containers()` — list all pocketdock managed containers (running and stopped)
+- `destroy_container(name)` — permanently remove a container regardless of persist setting
+- `prune()` — remove all stopped pocketdock managed containers
+- `ContainerListItem` dataclass with `id`, `name`, `status`, `image`, `created_at`, `persist`
+- `pocketdock.persist` and `pocketdock.created-at` labels on all containers
+- `list_containers()` and `commit_container()` socket client methods
+- All new functions available as sync (from `pocketdock`) and async (from `pocketdock.async_`)
+
+## [0.6.0] - 2026-02-09
+
+### Added
+
+- `AsyncSession` / `Session` — persistent shell sessions with state persistence (cwd, env vars, shell history)
+- `session()` method on `AsyncContainer` and `Container` to open a persistent shell
+- `send()` — fire-and-forget command to the shell
+- `send_and_wait()` — send a command and wait for completion with exit code, stdout, stderr, and duration
+- `read()` — drain accumulated output from the session (thread-safe)
+- `on_output()` — register callbacks for session output
+- `close()` — close the session without stopping the container
+- Sentinel protocol (`__PD_{uuid}_${?}__`) for reliable command boundary and exit code detection
+- `SessionClosed` error for operations on closed sessions
+- `attach_stdin` support in socket client `_exec_create()` for bidirectional exec connections
+- Automatic session cleanup during `shutdown()`
+- Exported `AsyncSession` from `pocketdock.async_` and `Session` (alias for `SyncSession`) from `pocketdock`
+
+## [0.5.0] - 2026-02-08
+
+### Added
+
+- `run(stream=True)` — streaming mode returns `AsyncExecStream` / `ExecStream` async iterator yielding `StreamChunk` objects in real-time
+- `run(detach=True)` — detached mode returns `AsyncProcess` / `Process` handle for background execution
+- `StreamChunk` dataclass with `stream` ("stdout"/"stderr") and `data` fields
+- `AsyncExecStream` / `ExecStream` — async iterator with `.result` property after iteration
+- `AsyncProcess` / `Process` — detached process handle with `id`, `is_running()`, `kill()`, `wait()`, `read()`, `peek()`, `buffer_size`, `buffer_overflow`
+- `RingBuffer` — thread-safe bounded ring buffer (1 MB default) for detached process output
+- `BufferSnapshot` dataclass with `stdout` and `stderr` strings
+- `CallbackRegistry` — register callbacks for stdout, stderr, and exit events
+- `on_stdout()`, `on_stderr()`, `on_exit()` callback methods on `AsyncContainer` and `Container`
+- `demux_stream_iter()` — incremental async generator for stream frame parsing
+- `_exec_start_stream()` — streaming exec with Docker chunked TE and Podman raw stream support
+- `_demux_chunked_stream()` — handles misalignment between HTTP chunk and demux frame boundaries
+- Automatic cleanup of active streams and processes in `shutdown()`
+- `@overload` type signatures on `run()` for all three output modes
+- Exported `ExecStream`, `Process`, `BufferSnapshot`, `StreamChunk` from `pocketdock`
+- Exported `AsyncExecStream`, `AsyncProcess` from `pocketdock.async_`
+
+## [0.4.0] - 2026-02-08
+
+### Added
+
+- `info()` — live container snapshot: status, uptime, memory, CPU, PIDs, processes, network
+- `reboot()` — restart in place; `reboot(fresh=True)` recreates with same config
+- `mem_limit` parameter for `create_new_container()` (e.g. `"256m"`, `"1g"`)
+- `cpu_percent` parameter for `create_new_container()` (e.g. `50` for 50% CPU cap)
+- `ContainerInfo` dataclass with 15 fields for container introspection
+- `get_container_stats()`, `get_container_top()`, `restart_container()` socket client endpoints
+- `_helpers.py` module with `format_bytes`, `parse_mem_limit`, `parse_iso_timestamp`, `compute_cpu_percent`
+- Resource limits via `HostConfig` (`Memory`, `NanoCpus`) in container creation
+- All new methods available on both `AsyncContainer` (async) and `Container` (sync)
+
+## [0.3.0] - 2026-02-07
+
+### Added
+
+- `write_file()` — write text or binary content into the container via tar archive API
+- `read_file()` — read file contents from the container via tar archive API
+- `list_files()` — list directory contents inside the container
+- `push()` — copy a file or directory from the host into the container
+- `pull()` — copy a file or directory from the container to the host
+- `push_archive()` and `pull_archive()` in socket client for raw tar transfer
+- All methods available on both `AsyncContainer` (async) and `Container` (sync)
+
+## [0.2.0] - 2026-02-07
+
+### Added
+
+- `AsyncContainer` class with async `run()`, `shutdown()`, and context manager
+- `Container` class (sync facade) with background event loop thread
+- `create_new_container()` factory function (sync in `pocketdock`, async in `pocketdock.async_`)
+- Blocking `run()` with configurable timeout and output capping
+- `lang` parameter for `run()` (e.g. `lang="python"` wraps command with `python3 -c`)
+- Timeout support in `exec_command` via `asyncio.wait_for`
+- Container labels (`pocketdock.managed`, `pocketdock.instance`) for discovery
+- Auto-generated container names (`pd-{8 hex}`)
+- Multiple independent containers from a single process
+- Thread-safe sync facade via `asyncio.run_coroutine_threadsafe`
+
+## [0.1.0] - 2026-02-07
+
+### Added
+
+- Project scaffold: README, CONTRIBUTING, LICENSE (BSD-2-Clause), docs site, CI pipeline
+- Async socket client over Unix socket (`_socket_client.py`)
+- HTTP/1.1 request/response over Unix domain sockets
+- Stream demultiplexing for Docker/Podman exec stream protocol (`_stream.py`)
+- Podman and Docker socket auto-detection
+- Container lifecycle operations: create, start, stop, remove, inspect
+- Exec command with stdout/stderr demux and exit code retrieval
+- Error hierarchy: `PocketDockError`, `SocketError`, `ContainerError`, `ImageNotFound`
+- `ExecResult` dataclass with `ok` property, timing, and truncation tracking
+- Minimal container image Dockerfile (Alpine 3.21 + Python + bash, ~25MB)
+- GitHub Actions CI: lint + test matrix (Python 3.10-3.13) + docs + audit
+- Pre-commit hooks: ruff, mypy, bandit, check-manifest
+- mkdocs-material documentation site
+- PEP 561 `py.typed` marker for type checking support

pocketdock-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to pocketdock
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/deftio/pocketdock.git
+cd pocketdock
+
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies
+uv sync --dev
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## Quality Bar
+
+Every commit must pass:
+
+- **100% line coverage** — no `# pragma: no cover`, no exclusions
+- **Zero ruff warnings** — `select = ["ALL"]`, `ignore = ["D1"]`
+- **mypy --strict clean** — every function has type annotations
+- **bandit clean** — security linting for socket/file/tar operations
+- **BSD-2-Clause SPDX header** in every `.py` source file under `python/pocketdock/`
+
+## Running Checks
+
+```bash
+uv run ruff check .                                 # Lint
+uv run ruff format --check .                        # Format check
+uv run mypy --strict python/pocketdock/            # Type check
+uv run bandit -r python/pocketdock/ -c pyproject.toml  # Security lint
+uv run pytest                                       # Tests (100% coverage)
+```
+
+## Test Strategy
+
+All tests are integration tests against a real Podman socket. No mocks.
+
+- Tests skip gracefully if no Podman socket is found locally
+- CI always has Podman available — all tests must pass there
+- Use the `minimal` profile (~25MB, <500ms startup) for tests
+
+## Git Workflow
+
+- **Branch naming**: `{type}/{description}` — e.g., `feat/m1-blocking-run`, `fix/stream-demux`
+- **Commit messages**: Conventional prefix — `feat:`, `fix:`, `test:`, `docs:`, `ci:`, `refactor:`
+- **Development cycle**: TDD — write tests first, red, implement, green, full lint suite, doc sync, PR
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the BSD-2-Clause license.

pocketdock-1.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) deftio llc
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pocketdock-1.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: pocketdock
+Version: 1.1.0
+Summary: Portable, offline-first container sandboxes for LLM agents and dev workflows
+Author: deftio llc
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: cli
+Requires-Dist: click; extra == 'cli'
+Requires-Dist: rich; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# pocketdock
+
+[![CI](https://github.com/deftio/pocketdock/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/pocketdock/actions/workflows/ci.yml)
+[![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%2Fpocket--dock-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
+- **Container persistence** — stop/resume, snapshot to image, volume mounts
+- **Project management** — `.pocketdock/` project directories with config, logging, and health checks
+- **Image profiles** — four pre-baked Dockerfiles: minimal, dev, agent, embedded
+- **Full CLI** — 21 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 only (zero dependencies)
+pip install pocketdock[cli]     # SDK + CLI (click, rich)
+```
+
+Requires [Podman](https://podman.io/getting-started/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).
+
+```bash
+# Build the minimal image (~25MB, <500ms startup)
+pocketdock build minimal
+```
+
+## 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 21 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.