# Virtualenvs survive sandbox checkpoints, and a failed capture frees the session

> Agno's DockerSandbox now keeps the absolute interpreter link that python -m venv creates and recreates it in the next container. A turn whose files a checkpoint cannot hold ends in ERROR with retryable set to False, and the session moves on from its previous checkpoint.

- Published: 2026-10-20
- Author: Yash Pratap Solanky
- Categories: Changelog
- Canonical: https://www.agno.com/blog/virtualenvs-survive-sandbox-checkpoints-and-a-failed-capture-frees-the-session
- Markdown: https://www.agno.com/blog/virtualenvs-survive-sandbox-checkpoints-and-a-failed-capture-frees-the-session.md

Running `python -m venv` in an Agno `DockerSandbox` used to lock the session until someone edited the database by hand. The command creates interpreter links like `.venv/bin/python -> /usr/local/bin/python`, and earlier releases refused that absolute link when they checkpointed the turn. The run raised `SandboxError`, the session binding stayed in `finalizing`, and every later run on that session got `SandboxSessionBusy`.

Checkpoints now store a symlink to an absolute path as its target string alone, with no bytes from behind it. A restore inside the next container recreates the link, so the venv runs on a fresh generation without a reinstall. A host-side `CheckpointArchive.restore`, the call you make after `agent.open_run_checkpoint`, leaves these links out, so nothing extracted on your machine points at your own files.

Special files such as a FIFO, links that escape their root, and trees over the archive limits still can't go in a checkpoint. They now raise `CheckpointContentError`, and the coordinator ends the turn in `ERROR` with `retryable: False` and the offending path in the run content. It retires the computer and releases the session, and the next turn starts from the previous checkpoint without the failed turn's files. Other capture failures, such as an unavailable checkpoint store, still leave the turn finalizing so a retry of the same run checkpoints it without repeating its tools.

We ran a `FixtureAgent` in a real `DockerSandbox` with the fixture runtime standing in for the model, and created a venv in the warm container between turns 1 and 2.

```text
# Before (real output, earlier release)
$ ls -l .venv/bin/python*
.venv/bin/python -> /usr/local/bin/python
.venv/bin/python3 -> python
Turn 2: raised SandboxError: Unsafe checkpoint symlink 'workspace/.venv/bin/python' -> '/usr/local/bin/python'; exclude it before capture
  binding: {'phase': 'finalizing', 'stop_status': None}
# retry the same run
Turn 2: raised SandboxError: Unsafe checkpoint symlink 'workspace/.venv/bin/python' -> '/usr/local/bin/python'; exclude it before capture
  binding: {'phase': 'finalizing', 'stop_status': None}
Turn 3: raised SandboxSessionBusy: A sandbox session already has an active run; wait or reconcile that run

# Now (real output, same steps)
Turn 2: status=COMPLETED
  binding: {'phase': 'idle', 'stop_status': None}
Turn 3: status=COMPLETED
Destroyed the computer; turn 4 restores cold from the checkpoint
Turn 4: status=COMPLETED
  $ readlink .venv/bin/python; .venv/bin/python -V: /usr/local/bin/python | Python 3.12.15
```

A second session that leaves a FIFO (`mkfifo /workspace/pipe`) in the workspace shows the release path. On the earlier release it stuck in `finalizing` the same way.

```text
# Now (real output)
Turn 2: status=ERROR {'retryable': False, 'workspace_rolled_back': True}
  content: Completed turn's files cannot be checkpointed, so they were discarded and the session continues from the previous checkpoint: Checkpoint contains an unsupported file type at 'workspace/pipe'; exclude it before capture
  binding: {'phase': 'idle', 'stop_status': 'ERROR'}
Turn 3: status=COMPLETED
  $ ls /workspace: ['fixture-effects.txt', 'fixture-env.txt']
```

Yash Pratap Solanky also made a cancelled `S3CheckpointStore.aopen_archive` delete the copy it had already downloaded to `scratch=`, which earlier releases left on disk.

See the [Docker sandbox cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/frameworks/sandbox/docker/README.md), and learn more about checkpoint archives in the [sandbox README](https://github.com/agno-agi/agno/blob/main/cookbook/frameworks/sandbox/README.md).