> **⚠️ DEPRECATED — REDUNDANT IMPLEMENTATION**
>
> This document is kept for historical reference only. It was the first draft of the taupocket design, generated by Perplexity and constrained by a heavy-handed prompt to "eliminate Hermes / Debian / Nix / QEMU / filesystem snapshots / duplicate substrates" — most of which were never on the table, and several of which (`smolvm hermes start`, `smolvm sandbox snapshot …`) are first-class smolvm features.
>
> **Superseded by [`TUTORIAL.md`](./TUTORIAL.md)**, which:
>
> - Uses `smolvm sandbox {create, exec, snapshot, file, port, shell, …}` directly instead of designing a custom snapshot model on top of smolvm's own snapshot primitives.
> - Documents how to import `/teacher-mode` and a custom `~/.tau` into a sandbox (`file upload` + tarball, or `--mount` + `--writable-mounts`).
> - Leaves the door open to Pi and other bundled agents (`smolvm pi start`, `smolvm hermes start`, …) instead of single-vendor-locking on Tau.
> - Covers the three export tiers honestly: snapshot-tree copy, workspace tarball, and `smolvm pack` (the last only on builds that ship it — this host's build does not).
>
> If you're landing here from a search result, **read `TUTORIAL.md` instead.** The recipe in its §8 is the whole project.

---

<img src="https://r2cdn.perplexity.ai/pplx-full-logo-primary-dark%402x.png" style="height:64px;margin-right:32px"/>

# eliminate hermes from the picture, debian is also a non-portable option. The agentic framework is tau, so eliminate all burden and duplicate options that suppose more time / space /resouces / overburden / non-portability. Eliminate also all mentions to discarded / legacy / non-viable options

Here’s a streamlined, portable‑only version that centers Tau and smolVM, drops Hermes/Debian/Nix/QEMU/filesystem snapshots, and avoids duplicate substrate options.[^1][^2][^3][^4][^5]

***

# Portable Tau Sandboxes with smolVM

## Overview

This project defines a **portable snapshot sandbox** for Hugging Face’s Tau coding agent using **smolVM** as the only runtime substrate.[^2][^5][^1]
The goal is to keep the design minimal: one agentic framework (Tau), one portable machine format (`.smolmachine`), and a small Git + changelog overlay for learning history.[^3][^4][^5]

Key properties:

- **Tau** is a minimalist terminal coding agent that reads files, edits code, runs commands, and maintains durable session history.[^4][^6][^3]
- **smolVM** packs a Linux VM into a single portable file (`.smolmachine`) with sub‑200ms cold boot and hardware isolation per workload.[^7][^8][^1][^2]
- **Snapshots** are just `.smolmachine` files (and optional Git commits) that can be copied, versioned, and restored on any supported host, with no dependency on host filesystem features.[^8][^5][^1][^2]

No other substrates, OS assumptions, or host‑specific snapshot mechanisms are part of this design.

***

## Core Design

### Single Agentic Framework: Tau

Tau is a small, layered coding agent:[^6][^3][^4]

- `tau_ai`: provider‑neutral event stream from any supported language model endpoint.[^3][^4][^6]
- `tau_agent`: portable agent “brain” (messages, tools, events, loop, harness, sessions).[^4][^6][^3]
- `tau_coding`: terminal application (CLI/TUI) with file/shell tools, skills, prompts, and on‑disk sessions.[^9][^3][^4]

This project treats Tau as:

- The **only** agentic framework.
- Both a working coding assistant and an educational blueprint for agent architecture.[^9][^6][^3][^4]


### Single Runtime Substrate: smolVM

smolVM is a CLI tool to build and run **portable, lightweight, self‑contained VMs**:[^1][^2][^7][^8]

- Sub‑second (often <200ms) cold boot times.[^2][^7][^8][^1]
- Each workload gets its own kernel boundary, not just container namespaces.[^7][^8][^1][^2]
- A stateful VM can be packed into one `.smolmachine` file that runs anywhere the architecture matches.[^10][^8][^1][^2][^7]

This project uses smolVM as the **only** sandbox substrate:

- No containers, no other hypervisors, no filesystem snapshots.[^5]

***

## Portable Snapshot Model

### Snapshot as a `.smolmachine` File

A snapshot is a single portable artifact:

- A `.smolmachine` file containing:
    - Minimal Linux userland.
    - Tau installed via `uv tool install tau-ai` or equivalent.[^6][^3][^4]
    - A `/workspace` directory for code, skills, curricula, and logs.[^5][^1][^2]

Creation flow (coarse‑grained snapshot):

1. Run Tau inside a smolVM machine until a learning milestone or stable state is reached.
2. Stop the machine (or flush state to disk).
3. Pack or copy the VM as a `.smolmachine` using smolVM’s `pack` or `machine` commands.[^10][^1][^2]
4. Save the artifact under a meaningful name, e.g. `tau-sandbox-m1.smolmachine`.[^5]

Restoration flow:

1. On any supported host, run smolVM against the chosen `.smolmachine`.
2. Tau starts inside the VM, seeing exactly the same environment and `/workspace` state as at snapshot time.[^8][^1][^2]
3. A restore event is logged in the changelog (see below).

No host‑specific snapshot APIs or OS assumptions are needed; the `.smolmachine` file is the snapshot.

### Optional Git Overlay (Fine-Grained History)

Inside `/workspace`, a Git repo captures **fine‑grained project history**:[^3][^4][^5]

- Tau skills (Markdown), prompts, and teacher‑mode scripts.
- Exercises, curriculum materials, and documentation.
- Code created or modified during sessions.

Typical pattern:

- After a session, the agent or supervising process identifies “promotable” changes (e.g. new skill, refactor).
- These changes are committed inside the VM, resulting in a Git history that lives inside `/workspace` and travels with the `.smolmachine`.[^11][^3][^5]

Git is optional but strongly recommended:

- It provides fine‑grained diffs and branches inside a snapshot.
- It is substrate‑agnostic and works entirely within the VM.

***

## Teacher Mode \& Learning Timeline

Although this design removes references to specific host assistants, it still assumes **teacher‑mode behavior** inside Tau:

- Teacher skills (stored as Markdown in `/workspace/skills`) describe educational flows:
    - Orientation: explore Tau architecture and logs before editing code.
    - Safe experimentation: practice with Git branching and snapshot restore.
    - Self‑modification: let Tau propose changes to skills under guardrails.[^9][^6]
- Tau’s TUI/CLI and skill system are used to implement:
    - Socratic prompts (“Predict what happens if we run this command”).
    - Reflection (“Summarize what changed since the last snapshot”).
    - Gradual autonomy (from guided tasks to open‑ended self‑modifying experiments).[^4][^3][^9]


### Changelog for Snapshots

In addition to Git, a simple **changelog file** (e.g. `changelog.jsonl` or `CHANGELOG.md` in `/workspace`) records:

- For each snapshot creation:
    - Timestamp.
    - Snapshot ID (`.smolmachine` filename and hash).
    - Current Git commit (if present).
    - Short summary of the learning milestone (e.g. “Added basic Git teacher skills”).[^5]
- For each snapshot restore:
    - Timestamp.
    - Snapshot ID restored.
    - Reason (“Replay intro module”, “Roll back broken experiment”).[^5]

This keeps mechanical state (snapshot file) and conceptual state (why we care about it) aligned without any external framework.

***

## Operational Flow (Single-Substrate, Minimal-Overhead)

### 1. Build the Base Machine

On a host with smolVM installed:[^1][^2][^8]

1. Use `smolvm machine run` or `smolvm pack create` to derive a base environment from a standard image (e.g. `python:3.12-alpine`).[^2][^8][^10][^1]
2. Inside the VM, install Tau via `uv tool install tau-ai`.[^6][^3][^4]
3. Create `/workspace` and initialize a Git repo if desired.
4. Save this as `tau-sandbox-base.smolmachine`.

From now on, every sandbox session runs inside clones or derivatives of this base machine.

### 2. Run Tau Sessions

For each learning session:

1. Start a smolVM machine from `tau-sandbox-base.smolmachine` or a derived snapshot (e.g. `tau-sandbox-m1.smolmachine`).[^8][^1][^2][^5]
2. Run Tau from `/workspace`, connecting it to a language model provider via Tau’s `/login` mechanism.[^3][^4][^9]
3. Use Tau’s tools and skills to explore, edit, and run code; logs and session exports remain inside the VM.[^4][^6][^3]

### 3. Create a Snapshot

When a meaningful state is reached:

1. Ensure `/workspace` is consistent (optional: run tests, lint).
2. Stop the machine or persist state.
3. Use smolVM to pack or copy the VM into `tau-sandbox-mN.smolmachine`.[^10][^1][^2][^8]
4. Inside `/workspace`:
    - Commit any promoted changes to Git.
    - Append a changelog entry describing the snapshot.[^5]

### 4. Restore a Snapshot

To revisit a previous milestone:

1. Pick the desired `.smolmachine` file.
2. Start a new machine from that artifact.
3. Run Tau; it sees the restored `/workspace` and Git state.
4. Append a restore event to the changelog to keep the timeline coherent.[^5]

***

## Roadmap (Minimal Version)

### Phase 1 – Base Tau Machine

- Install smolVM on a supported host.[^1][^2][^8]
- Build `tau-sandbox-base.smolmachine` with:
    - Linux image.
    - Python + `uv`.
    - Tau installed (`uv tool install tau-ai`).[^6][^3][^4]
    - Empty `/workspace` (Git optional).


### Phase 2 – Snapshot \& Changelog Wiring

- Define a naming convention for snapshots (e.g. `tau-sandbox-m1`, `m2`, …).
- Implement scripts or simple commands to:
    - Create new `.smolmachine` snapshots.
    - Compute checksums for integrity.
- Add a `changelog` file inside `/workspace` with entries for snapshot create/restore.[^5]


### Phase 3 – Teacher Skills \& Curriculum

- Create Tau skills for:
    - Intro to Tau architecture and session logs.
    - Git basics and snapshot reasoning.
    - Safe self‑modification patterns.[^9][^3][^4]
- Run sessions inside the smolVM sandbox using these skills; snapshot after each module.


### Phase 4 – Self-Modifying Tau Experiments

- Let Tau propose changes to skills and curriculum files under guided prompts.
- Use Git commits + `.smolmachine` snapshots as guardrails:
    - Each experiment is attached to a specific snapshot tag.
    - Revert to previous tags when experiments fail.

***

This version keeps only Tau + smolVM + Git/changelog, with snapshots as `.smolmachine` files. There are no references to Hermes, Debian, Nix, QEMU, filesystem‑dependent snapshotting, or alternative substrates, so overhead and non‑portability are minimized while preserving a clear agentic/educational story.[^2][^1][^3][^4][^5]
<span style="display:none">[^12][^13][^14][^15][^16][^17]</span>

<div align="center">⁂</div>

[^1]: https://github.com/smol-machines/smolvm

[^2]: https://daniliants.com/insights/github-smol-machines-smolvm-portable-lightweight-vms/

[^3]: https://www.sourcepulse.org/projects/32201187

[^4]: https://www.everydev.ai/tools/tau-ai

[^5]: Decision-Summary_-Portable-Snapshot-Sandboxes-for.md

[^6]: https://techbytes.app/posts/huggingface-released-tau-a-coding-agent-2/

[^7]: https://www.youtube.com/watch?v=2PoW1OWbfkw

[^8]: https://byteiota.com/smolvm-portable-vms-boot-in-200ms-solve-works-on-my-machine/

[^9]: https://www.youtube.com/watch?v=qo1QNxWcm28

[^10]: https://github.com/smol-machines/smolvm/blob/main/AGENTS.md

[^11]: https://addyosmani.com/blog/self-improving-agents/

[^12]: https://deepwiki.com/huggingface/tau/7-cli-and-print-mode

[^13]: https://deepwiki.com/huggingface/tau/2.3-tau_coding:-coding-agent-application

[^14]: https://daily.dev/posts/github---smol-machines-smolvm-tool-to-build-run-portable-lightweight-self-contained-virtual-mac-ypwlwu4wm

[^15]: https://orply.com/articles/hugging-face/tau-crash-course-the-python-port-of-pi-2c258178

[^16]: https://reporank.net/vi/repo/huggingface-tau.html

[^17]: https://www.youtube.com/watch?v=EjgFvXTJhjA\&vl=ru