{"id":44942973,"url":"https://github.com/deftio/pocketdock","last_synced_at":"2026-02-18T09:07:32.432Z","repository":{"id":337357088,"uuid":"1151963574","full_name":"deftio/pocketdock","owner":"deftio","description":"a docker / podman style sandbox for coding agents and experiments with cli, python api, logging, and simple commands.","archived":false,"fork":false,"pushed_at":"2026-02-11T19:06:07.000Z","size":1031,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T02:37:57.449Z","etag":null,"topics":["cli","docker","llm-docker","podman","python-docker","python-docker-development","sandbox"],"latest_commit_sha":null,"homepage":"https://deftio.github.io/pocket-dock/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deftio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T06:24:45.000Z","updated_at":"2026-02-11T19:05:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deftio/pocketdock","commit_stats":null,"previous_names":["deftio/pocket-dock","deftio/pocketdock"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/deftio/pocketdock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deftio%2Fpocketdock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deftio%2Fpocketdock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deftio%2Fpocketdock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deftio%2Fpocketdock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deftio","download_url":"https://codeload.github.com/deftio/pocketdock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deftio%2Fpocketdock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29574068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","llm-docker","podman","python-docker","python-docker-development","sandbox"],"created_at":"2026-02-18T09:07:30.827Z","updated_at":"2026-02-18T09:07:32.426Z","avatar_url":"https://github.com/deftio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pocketdock\n\n[![CI](https://github.com/deftio/pocketdock/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/pocketdock/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/pocketdock)](https://pypi.org/project/pocketdock/)\n[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/deftio/pocketdock/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-deftio.github.io%2Fpocketdock-blue)](https://deftio.github.io/pocketdock/)\n[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD_2--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)\n\n**Portable, offline-first container sandboxes for LLM agents and dev workflows.**\n\nOne Container class. Podman-first, Docker-compatible. Python SDK + CLI. Zero cloud. Zero API keys.\n\n## Why pocketdock?\n\nManaged 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.\n\n## Features\n\n- **Three execution modes** — blocking, streaming, and detached (background) with ring buffer\n- **File operations** — read, write, list, push, and pull files between host and container\n- **Persistent sessions** — long-lived shell sessions with state (cwd, env vars, history)\n- **Resource limits** — memory caps, CPU throttling, per-container isolation\n- **Port mapping** — expose container ports on the host (e.g., `ports={8080: 80}`)\n- **Container persistence** — stop/resume, snapshot to image, volume mounts\n- **Project management** — `.pocketdock/` project directories with config, logging, and health checks\n- **Image profiles** — six pre-baked Dockerfiles: minimal-python, minimal-node, minimal-bun, dev, agent, embedded\n- **Full CLI** — 22 commands for container lifecycle, file ops, and project management\n- **Async-first** — sync facade over async core; use either API style\n- **Callbacks** — register handlers for stdout, stderr, and exit events\n\n## Quick Example\n\n```python\nfrom pocketdock import create_new_container\n\nwith create_new_container() as c:\n    result = c.run(\"echo hello\")\n    print(result.stdout)  # \"hello\\n\"\n    print(result.ok)      # True\n```\n\n## Install\n\n```bash\npip install pocketdock          # SDK + CLI (includes click, rich)\npip install pocketdock[agent]   # + LLM agent (litellm, python-dotenv)\n```\n\nSingle-file downloads (no pip required) are available from [GitHub Releases](https://github.com/deftio/pocketdock/releases).\n\nRequires [Podman](https://podman.io/getting-started/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/).\n\n```bash\n# Build the minimal-python image (~25MB, \u003c500ms startup)\npocketdock build minimal-python\n```\n\n## Documentation\n\nFull documentation is available at **[deftio.github.io/pocketdock](https://deftio.github.io/pocketdock/)**.\n\n- [Quickstart](https://deftio.github.io/pocketdock/quickstart/) — install, build, run your first container\n- [User Guide](https://deftio.github.io/pocketdock/guide/containers/) — containers, commands, files, sessions, persistence, profiles\n- [CLI Reference](https://deftio.github.io/pocketdock/cli/) — all 22 commands with examples\n- [API Reference](https://deftio.github.io/pocketdock/reference/api/) — full SDK reference\n\n## Architecture\n\n```\nUser Code / LLM Agent / CLI\n        |\n        v\n  pocketdock SDK\n  +--------------------------------------+\n  | Container (sync)  -\u003e AsyncContainer  |  facade pattern\n  |   +- _socket_client (raw HTTP/Unix)  |\n  +- ProjectManager (.pocketdock/)      |\n  +- Persistence (resume, snapshot)      |\n  +- Sessions (persistent shells)        |\n  +--------------------------------------+\n        |  raw HTTP over Unix socket\n        |  (one connection per operation)\n        v\n  Podman (rootless) / Docker Engine\n```\n\n**Design principles:**\n\n- **Connection-per-operation** — each API call opens its own Unix socket. No pooling.\n- **Async core, sync facade** — `AsyncContainer` does all real work. `Container` is a sync wrapper.\n- **No cached state** — always polls live from the engine.\n- **Minimal dependencies** — stdlib-only for the core SDK.\n\n## Development\n\n```bash\nuv sync --dev                    # Install dependencies\nuv run pytest                    # Run tests (100% coverage enforced)\nuv run ruff check .              # Lint (zero warnings)\nuv run mypy --strict python/     # Type checking (strict mode)\nuv run mkdocs serve              # Local docs site\n```\n\n## License\n\nBSD-2-Clause. Copyright (c) deftio llc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeftio%2Fpocketdock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeftio%2Fpocketdock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeftio%2Fpocketdock/lists"}