Potpie Files

v1.1.0

Sandbox-native agent execution with multi-backend support, bare-repo caching, and a revamped toolset for dramatic speed and token efficiency gains.

What's Changed

This release introduces a foundational rework of how Potpie agents execute against repositories. Agents no longer operate directly on the host filesystem or pay the cost of a full git clone per session. Instead, all repository interactions flow through a new provider-agnostic sandbox layer that manages durable bare-repo caches, ephemeral git worktrees, and swappable execution backends: Local subprocess, Docker, Daytona, and NFS mounts, with e2b support on the roadmap. The agent toolset has also been rebuilt from scratch, replacing fragmented legacy tools with a unified sandbox_* interface that ships pre-bound to a workspace handle at session start, delivering measurable improvements in provisioning latency and token efficiency.

Highlights

Multi-Environment Sandbox Architecture

• New Ports & Providers pattern (via Python Protocol) decouples workspace management from execution — workspace providers handle the filesystem and git layer; runtime providers handle process isolation
• Local subprocess provider for development and read-only analysis with zero overhead
• Docker provider using the CLI (no heavy Python SDK dependency) with docker exec dispatch, bind mounts, and resource limits
• Daytona provider for managed, scalable sandboxes: one sandbox per user/project with multiple branch worktrees via git worktree
• Snapshot auto-build from bundled Dockerfile on-demand
• Optional bare-cache volumes persisting clones across sandbox lifecycle events
• Self-healing recovery via managed-by=potpie labels when process restarts
• 24-hour auto-stop TTL (configurable), 30-day auto-archive TTL
• NFS-backed deployment support via shared .repos mount across Potpie service instances
• e2b sandbox integration coming soon

Revamped Agent Toolset

• Consolidated sandbox_text_editor, sandbox_shell, sandbox_search, sandbox_git, and sandbox_pr replacing fragmented legacy tools
• Tools are now pre-bound to a WorkspaceHandle at session start (explicit mode), eliminating per-call project resolution overhead
• Capability-gated tools: write operations (str_replace, commit, push) are automatically omitted from read-only workspaces

Performance

• Provision-on-parse: RepoCache is eagerly warmed when a repo finishes parsing — agents are ready to work at first invocation, not after a cold clone
• Direct FS fast path: SandboxClient uses host filesystem access on local backends and native Daytona SDK calls (sandbox.fs.download_file) where available, falling back to exec only when necessary
• Line-level file reads: view_range parameter lets agents read specific line ranges instead of ingesting entire files
• Structured tool output: Search and git tools return JSON rather than raw shell text, formatted optimally for LLM context windows
• Output capping: Shell output truncated at 80KB, search at 200 hits which prevents context overflow

Security & Isolation

• Explicit Capabilities model: Every workspace carries writable, isolated, and persistent flags enforced at the adapter boundary
• Auth token hygiene: Git credentials injected per-call via git -c http.<host>.extraheader=... and never written to .git/config
• Path sandboxing: SandboxClient validates relative paths, rejects .. traversal, and resolves symlinks on local backends
• Bot identity injection: GIT_AUTHOR_* and GIT_COMMITTER_* set in the runtime environment for correct commit attribution

Deprecations

• Direct filesystem tools (non-sandbox) are deprecated in favor of the sandbox_* toolset
• LocalSubprocessRuntimeProvider with allow_write=True is not a security boundary and should not be used for untrusted workloads

Merged PRs

• Feat/context engine by @nndn in https://github.com/potpie-ai/potpie/pull/749

Full Changelog: https://github.com/potpie-ai/potpie/compare/1.0.2...v1.1.0