Environments: no snapshot/reuse — every provision re-installs from scratch; add capture-after-setup keyed by definition hash (docker commit, native cloud snapshots) + `praisonai env rebuild/list/prune`

[MervinPraison]

Aim

Make provisioned agent environments fast to reuse: after the environment definition's packages install and setup: commands run once, capture that state and start subsequent runs from the capture instead of re-installing from scratch every time. Target: second-and-later runs start in seconds. This is the speed half of the environments work and depends on the definition sibling (#3669) — the capture is keyed by a hash of the definition, so any change to it invalidates cleanly.

Current behaviour (every run pays full setup; capture primitives unused)

Validated on current main:

1. Zero environment snapshots anywhere. grep -rni "snapshot" across all packages returns only file/context/skill/config snapshots (paths.py:200-207, trace/context_events.py:155, skills/manager.py:865-871, …). praisonai_sandbox/ contains 0 occurrences of the word. No commit, pause, fork, or image-cache concept in either execution stack.
2. Everything is ephemeral by design today: the docker sandbox backend's start() only pulls the base image and each execute() is a fresh docker run (praisonai_sandbox/docker.py:79-100, 278, 430-457); the daytona backend creates a sandbox per session and destroys it on cleanup (daytona.py:96-116). ComputeProviderProtocol has provision/execute/shutdown — no snapshot method (praisonaiagents/managed/protocols.py:91+).
3. The cloud SDKs already support capture and it's unused: the E2B and Daytona SDKs natively support sandbox pause/snapshot/resume; PraisonAI's adapters never call them. Docker supports commit for image capture; unused.
4. The only related CLI verb is the opposite of a capture: praisonai sandbox recreate deletes containers so they rebuild from base (praisonai_code/cli/commands/sandbox.py:230-292).
5. Consequence once Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669 lands: a definition with packages + setup: would re-run installs on every provision — kanban boards spawning many workers pay it per worker; iterative sandbox run pays it per invocation.

Desired behaviour

1. Capture-after-setup, keyed by definition hash. When an environment is provisioned from .praisonai/environment.yaml (Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669), after packages+setup: succeed the backend captures the state:
   • docker → docker commit to a local image praisonai-env:{hash12};
   • e2b / daytona → the SDK's native snapshot/pause primitive, id recorded;
   • subprocess/sandlock/ssh → no capture (documented no-op; nothing to capture or capture is meaningless).
2. Reuse on match: next provision with the same definition hash starts from the capture (skip pull+install+setup). Any change to the definition file → new hash → fresh build then new capture. Manual refresh: praisonai env rebuild (capture invalidate + rebuild).
3. Optional refresh hook: a refresh: command list in the definition runs when starting from a capture (e.g. pip install -e . to catch code changes) — cheap incremental step, never the full setup.
4. Bookkeeping: captures recorded in ~/.praisonai/environments/registry.json {definition_hash: {backend, ref, created_at, last_used}}; praisonai env list shows them; age-based GC (default 14 days unused) with praisonai env prune.
5. Safety/defaults: capture is on by default only for backends where it is free and local (docker commit); cloud snapshot capture is opt-in per definition (capture: true) since it may carry provider cost. A failed capture degrades to today's ephemeral behaviour with a log line — never blocks the run.

Layer placement

• Core (praisonaiagents): one optional protocol addition — capture(instance) -> ref / provision_from(ref) on the compute/sandbox protocols (default NotImplemented → ephemeral path), plus the definition-hash helper.
• praisonai-sandbox / wrapper integrations/compute/: per-backend implementations (docker commit; e2b/daytona SDK snapshot calls behind their existing extras).
• praisonai-code: env rebuild/list/prune verbs beside env init/validate/show (Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669).
• Why not core-heavy: capture mechanics are backend-specific and live with the backends; core holds only the tiny protocol + hash.
• Depends on: Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669 (the definition is the cache key and the setup being amortised).

Implementation plan

1. definition_hash(defn) -> str — stable sha256 over the normalised definition (image, packages, setup, env names, resources; exclude values marked secret).
2. Protocol: SupportsCapture (optional) on ComputeProviderProtocol/sandbox backend protocol; provision flow becomes: registry lookup by hash → provision_from(ref) + refresh: if hit → else full provision + setup → capture() → registry record.
3. Docker: docker commit {container} praisonai-env:{hash12} after setup (praisonai_sandbox/docker.py post-setup site; also the compute docker provider); provision-from = use that image instead of base.
4. E2B/Daytona: wire the SDKs' snapshot/pause+resume (praisonai_sandbox/e2b.py, daytona.py, integrations/compute/{e2b,daytona}.py) behind capture: true.
5. Registry + GC + CLI verbs (praisonai_code/cli/commands/): env list, env rebuild, env prune.
6. Docs: the run-twice contract — first run builds and captures; subsequent runs start from capture; edit the file → automatic rebuild.

Tests (TDD)

• test_definition_hash_stable_and_sensitive — reordering keys → same hash; changing a package → new hash.
• test_docker_capture_and_reuse — second provision with same definition skips setup (setup command spy called once) and starts from praisonai-env:{hash12}.
• test_definition_change_invalidates — edited file → full rebuild + new capture.
• test_refresh_runs_on_capture_start — refresh: executes only on capture-based starts.
• test_capture_failure_degrades_ephemeral — commit error → run proceeds as today, warning logged.
• test_noncapturing_backend_noop — subprocess backend unchanged.
• test_registry_gc_prune — unused entries pruned by age; env prune removes refs and (docker) images.

Severity

Medium-High — without reuse, the environment definition (#3669) makes every provision slower in exchange for reproducibility; with it, PraisonAI matches the fast-start property the major cloud coding agents converge on (setup-once-then-cached), and multi-worker kanban boards amortise setup across the fleet. The primitives (docker commit, cloud SDK snapshots) already exist under the adapters — this is wiring plus bookkeeping.

Validation (current main)

• No env snapshots: repo-wide grep (only file/context/skill snapshots); 0 hits in praisonai_sandbox/; no commit/pause/fork in either stack.
• Ephemeral flows: praisonai_sandbox/docker.py:79-100, 278, 430-457; daytona.py:96-116; ComputeProviderProtocol lacks capture (managed/protocols.py:91+).
• sandbox recreate destroys rather than captures: praisonai_code/cli/commands/sandbox.py:230-292.

Related

• Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669 — the environment definition (prerequisite; provides the cache key and the setup to amortise).
• Multi-agent: parallel kanban workers share one working directory — no per-task git worktree isolation or conflict-on-merge detection #3061 — kanban workers (chief beneficiary: N workers, one setup).

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Issue #3670 — Environment snapshot/reuse capture

• Read AGENTS.md & architecture guidelines
• Check whether Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669 (environment definition) has landed — it has not
• Critically review scope (lightweight & powerful; reject scope creep)
• Decide: minimal implementation vs. block on prerequisite

Decision: blocked on prerequisite #3669 — no PR created

This issue is the speed half of the environments work and, by its own framing, depends on #3669 ("the definition is the cache key and the setup being amortised"). I validated current main:

• Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669 is still OPEN and unimplemented. There is no .praisonai/environment.yaml, no definition loader, no definition_hash, and no praisonai env init/validate/show command group.
  • grep for environment.yaml / env init|validate|show in praisonai-code → 0 hits.
  • gh issue view 3669 → state: OPEN.
• The docker sandbox is ephemeral by design and has no setup step to amortise. docker.py:79-100 start() only docker pulls the base image; each execute() is a fresh docker run. There is no persistent container, no packages install, and no setup: phase today — those all arrive with Environments: no repo-committed execution-environment definition — add .praisonai/environment.yaml (image/packages/setup/resources) consumed by sandbox, compute, and kanban workers + praisonai env CLI #3669.
• Confirmed the issue's own premises: grep -rni "snapshot|docker commit|SupportsCapture|provision_from|definition_hash" src/praisonai-sandbox/ → 0 hits.

Why implementing now would be scope creep

Everything #3670 needs as input is owned by #3669:

#3670 needs	Provided by	Exists today?
definition_hash(defn) — the cache key	the definition (#3669)	❌
packages + setup: — the thing being cached/amortised	the definition (#3669)	❌
praisonai env … command group to add rebuild/list/prune beside	env init/validate/show (#3669)	❌

Building the SupportsCapture protocol, the ~/.praisonai/environments/registry.json, docker commit, and the CLI verbs now would add a protocol method, a wrapper subsystem, and three CLI verbs with no live consumer — the exact "knobs/modules/exports with no live consumer" that AGENTS.md and the project's lightweight-and-powerful mandate say to reject. There is literally nothing to hash and nothing to skip until the definition + setup step exist.

Recommendation

Keep this issue open and sequence it after #3669. Once the definition lands (environment.yaml loader, definition_hash primitive, and the packages+setup: provision flow), this becomes a clean, well-scoped follow-up:

1. SupportsCapture optional protocol (capture(instance) -> ref / provision_from(ref), default NotImplemented → ephemeral) on the sandbox/compute protocol in core.
2. Docker commit → praisonai-env:{hash12} at the post-setup: site; provision-from reuses that image.
3. Registry + age GC + env rebuild/list/prune beside env init/validate/show.
4. Cloud snapshots (e2b/daytona) behind capture: true, opt-in due to provider cost.

No code changes and no PR for now — implementing ahead of its prerequisite would add speculative surface area for a definition that doesn't yet exist. Happy to pick this up immediately once #3669 merges.

Job run · branch claude/issue-3670-20260804-1507

[MervinPraison]

@claude other issue is fixed , now continue with this

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-3670-20260805-0729 • [Create PR ➔](https://github.com/MervinPraison/PraisonAI/compare/main...claude/issue-3670-20260805-0729?quick_pull=1&title=Issue%20%233670%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%233670%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Issue #3670 — Environment snapshot/reuse capture

Done — implemented capture-after-setup env reuse keyed by definition hash.

PR: #3679

• Verify prerequisite (feat: add .praisonai/environment.yaml loader + ComputeConfig.setup #3671 merged: loader + ComputeConfig.setup)
• Core: definition_hash(config) + optional SupportsCapture protocol
• Loader: refresh: + capture: keys (carried in metadata, no new dataclass field)
• Docker: capture() (docker commit → praisonai-env:{hash12}), reuse-on-match, refresh: on hit, registry + list_captures/prune_captures, failure degrades to ephemeral
• Wire capture metadata through managed_local.provision_compute
• Tests — 24 core + 7 docker capture, all green
• Commit, push, open PR

What it does

After packages + setup: run once, the docker backend commits the container to a local image keyed by a stable definition hash; the next provision of the same definition starts from that capture (skips pull+install+setup). Edit the definition → new hash → rebuild + new capture. Optional refresh: runs only on capture hits. Failed capture silently degrades to today's ephemeral path.

Scope kept lightweight

Core holds only the tiny definition_hash + SupportsCapture protocol; all capture mechanics live with the docker backend (its live consumer is managed_local.provision_compute). The env rebuild/list/prune CLI verbs were deliberately not added — the env init/validate/show group they'd sit beside doesn't exist yet, so a new CLI group would be scope creep. Prune/list are tested provider methods a future env CLI can wrap. Cloud (e2b/daytona) snapshot capture is left behind the opt-in capture: flag for a follow-up (provider cost).

Note on test suite

5 unrelated tests/managed/ failures (compute-bridge async-mock brittleness + a stale LocalManagedAgent import) were verified to pre-exist on main via a baseline stash — not caused by this change.

Job run · branch claude/issue-3670-20260805-0729