Skip to content

Quickstart

Get a container running in under a minute.

Prerequisites

  • Python 3.10+
  • Container engine: Podman (recommended) or Docker

Install

pip install pocketdock          # SDK + CLI
pip install pocketdock[agent]   # + LLM agent

Build the Minimal Image

pocketdock ships Dockerfiles for six image profiles. The minimal-python profile (~25MB, <500ms startup) is the default:

pocketdock build minimal-python

Or build directly with your container engine:

# Podman
podman build -t pocketdock/minimal-python images/minimal-python/

# Docker
docker build -t pocketdock/minimal-python images/minimal-python/

Run Your First Container

from pocketdock import create_new_container

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

Context Manager

Use a context manager to automatically clean up the container:

from pocketdock import create_new_container

with create_new_container() as c:
    result = c.run("echo hello")
    print(result.stdout)
# Container is stopped and removed automatically

Run Python Code

Use the lang parameter to run code in a specific language:

with create_new_container() as c:
    result = c.run("print(2 + 2)", lang="python")
    print(result.stdout)  # "4\n"

File Operations

Read and write files inside the container:

with create_new_container() as c:
    c.write_file("/home/sandbox/hello.txt", "Hello from host!")
    data = c.read_file("/home/sandbox/hello.txt")
    print(data.decode())  # "Hello from host!"

    files = c.list_files("/home/sandbox/")
    print(files)  # ["hello.txt"]

Try the CLI

# Create a container using the minimal-python profile
pocketdock create --name my-sandbox --profile minimal-python

# Run a command
pocketdock run my-sandbox echo hello

# Interactive shell
pocketdock shell my-sandbox

# Clean up
pocketdock shutdown my-sandbox --yes

Web Server Demo

The minimal-python image includes a demo/ directory with a simple web page and server. Try it with port mapping:

# Create a container with host port 8080 mapped to container port 8000
pocketdock create --name my-web --profile minimal-python -p 8080:8000

# Open a shell and start the server
pocketdock shell my-web
cd demo && python serve.py

# Open http://localhost:8080 in your browser

The -p 8080:8000 flag maps host port 8080 to container port 8000. Port mapping must be set at container creation time.

# Clean up when done
pocketdock shutdown my-web --yes

Next Steps