v1.1.0

## 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