Projects¶

pocketdock projects group containers with a shared configuration directory (.pocketdock/) that lives next to your code.

Initialize a Project¶

from pocketdock import init_project

project_root = init_project()  # Creates .pocketdock/ in the current directory

Or specify a path:

project_root = init_project("/path/to/my-project")

With a custom project name:

project_root = init_project(project_name="my-app")

This creates:

my-project/
├── .pocketdock/
│   └── pocketdock.yaml
└── ... (your code)

Find Project Root¶

Walk up from a directory to find the nearest .pocketdock/pocketdock.yaml:

from pocketdock import find_project_root

root = find_project_root()  # Starts from cwd
root = find_project_root("/some/nested/dir")

Returns None if no project is found.

Project Configuration¶

The pocketdock.yaml file configures project defaults:

project_name: my-app
default_profile: minimal-python
default_persist: false
auto_log: true
max_log_size: 10MB
max_logs_per_instance: 100
retention_days: 30
socket: null
log_level: info

See Configuration for full details.

Associate Containers with a Project¶

Pass the project parameter when creating containers:

c = create_new_container(project="my-app", persist=True)

If you're inside a project directory, the project is auto-detected:

# Inside a directory with .pocketdock/pocketdock.yaml
c = create_new_container(persist=True)
# project is auto-detected from the nearest .pocketdock/

Instance Directories¶

Each persistent container in a project gets its own instance directory:

.pocketdock/
├── pocketdock.yaml
└── instances/
    └── my-sandbox/
        ├── instance.toml    # Container metadata
        ├── history.jsonl    # Command history
        └── logs/            # Session and detach logs

Instance Metadata¶

instance.toml contains container metadata:

container_id = "abc123..."
name = "my-sandbox"
image = "pocketdock/minimal-python"
project = "my-app"
created_at = "2026-01-15T10:30:00"
persist = true
mem_limit = "256m"
cpu_percent = 50

Command History¶

history.jsonl logs every run() call with timestamps, commands, exit codes, and durations.

Doctor¶

Diagnose project health by cross-referencing local instance directories with the container engine:

from pocketdock import doctor

report = doctor()
report.orphaned_containers    # Containers with no instance dir
report.stale_instance_dirs    # Instance dirs with no container
report.healthy                # Count of healthy container-dir pairs

The DoctorReport fields:

Field	Type	Description
`orphaned_containers`	`tuple[str, ...]`	Container names without matching instance dirs
`stale_instance_dirs`	`tuple[str, ...]`	Instance dir names without matching containers
`healthy`	`int`	Count of healthy pairs

ProjectNotInitialized¶

If doctor() is called outside a project directory, it raises ProjectNotInitialized:

from pocketdock import ProjectNotInitialized

try:
    report = doctor()
except ProjectNotInitialized:
    print("Run init_project() first")