Tutorial y tutorial desactualizado.
This commit is contained in:
parent
7fffb685a9
commit
e0a871523a
2 changed files with 711 additions and 0 deletions
442
TUTORIAL.md
Normal file
442
TUTORIAL.md
Normal file
|
|
@ -0,0 +1,442 @@
|
||||||
|
# Tau (and Pi) Pocket on smolvm — Tutorial
|
||||||
|
|
||||||
|
A self-contained guide to running **Tau**, the minimalist terminal coding agent, inside a **smolvm** sandbox, and bringing in your existing `/teacher-mode` skills.
|
||||||
|
|
||||||
|
> **Scope.** The substrate is smolvm. The primary agent is Tau. The door is left open for **Pi** (Tau's design inspiration) and for other smolvm-bundled agents — `smolvm hermes`, `smolvm claude`, `smolvm codex`, `smolvm openclaw` — but only one agent lives in a sandbox at a time.
|
||||||
|
>
|
||||||
|
> **What this replaces.** The earlier "Decision Summary" document in this folder was mostly a paraphrase of `smolvm --help` plus a hand-rolled snapshot model. The CLI already does snapshots (`smolvm sandbox snapshot ...`) and already ships first-class launchers for every popular agent. This tutorial uses those primitives directly. No custom substrate, no bespoke snapshot file format, no extra "Phase 1/2/3" rollout.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. Prerequisites
|
||||||
|
|
||||||
|
Verify the host can run smolvm:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm doctor
|
||||||
|
```
|
||||||
|
|
||||||
|
You want `Backend: firecracker` (or qemu / libkrun), `Result: OK`, and `kvm`/`network-permissions` to show **pass**. The four warnings shown on this machine (`nft-table:ip:smolvm` not created yet, swap enabled, thp enabled) are non-fatal — they self-resolve or are host-tuning, not blocking.
|
||||||
|
|
||||||
|
Confirm the smolvm build you have actually exposes the commands used here:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm --help # should list: claude codex hermes pi openclaw sandbox ...
|
||||||
|
smolvm sandbox --help # should list: create exec snapshot file ...
|
||||||
|
smolvm pack --help # OPTIONAL — read §6 before relying on this
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Caveat verified on this host:** this build of smolvm does **not** expose `smolvm machine ...` or `smolvm pack ...` (only `sandbox`, `browser`, and the agent launchers). Everything below is written for the `sandbox` family, which is what you have. The pack/machine flow is described in §6 for reference; if your build has it, use it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. The minimal mental model
|
||||||
|
|
||||||
|
You only need four smolvm primitives and three Tau facts:
|
||||||
|
|
||||||
|
| smolvm | What it does |
|
||||||
|
|---|---|
|
||||||
|
| `sandbox create` | Allocate a fresh Linux VM (alpine/ubuntu) with a name |
|
||||||
|
| `sandbox exec` | Run a command inside it (auto-starts the VM with `--start`) |
|
||||||
|
| `sandbox snapshot create / restore / list` | Save and rewind VM state — this is the "snapshot model" |
|
||||||
|
| `sandbox file upload / download` | Copy files in and out (sandbox must be running) |
|
||||||
|
|
||||||
|
| Tau | Where it lives |
|
||||||
|
|---|---|
|
||||||
|
| Sessions | `~/.tau/sessions/*.jsonl` (append-only) |
|
||||||
|
| Custom providers/models | `~/.tau/catalog.toml` |
|
||||||
|
| Project skills / instructions | `AGENTS.md`, `.tau/`, `.agents/` (loaded from cwd up) |
|
||||||
|
| Skills shipped with the repo | `tau_coding/skills/` (read-only) |
|
||||||
|
|
||||||
|
Pi keeps its config under `~/.pi/agent/` with skills at `~/.pi/agent/skills/`, sessions configurable via `PI_CODING_AGENT_SESSION_DIR` or settings.json. The two agents do not share state directories.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Build the base sandbox
|
||||||
|
|
||||||
|
Pick a name — `tau-pocket` is the convention used in the rest of this guide.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Alpine is small and fast for a coding-agent sandbox
|
||||||
|
smolvm sandbox create --name tau-pocket --os alpine --network nat
|
||||||
|
smolvm sandbox list # status: created
|
||||||
|
```
|
||||||
|
|
||||||
|
Install Tau **inside the sandbox** (one `exec` call chains everything):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec --start tau-pocket -- sh -lc '
|
||||||
|
apk add --no-cache python3 py3-pip git curl bash
|
||||||
|
pip install --break-system-packages uv
|
||||||
|
uv tool install tau-ai
|
||||||
|
uv tool dir # so you can see where tau-ai was installed
|
||||||
|
mkdir -p /workspace && cd /workspace && git init -q
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
Now, `/.local/bin` is not in the PATH, so we have to add it by hand:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec tau-pocket
|
||||||
|
```
|
||||||
|
|
||||||
|
No, we edit `/etc/profile` with `vi /etc/profile` and add './local/bin' at the end of the PATH line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/.local/bin"
|
||||||
|
```
|
||||||
|
|
||||||
|
We save the file and exit the VM with CTRL+d.
|
||||||
|
|
||||||
|
Sanity check before snapshotting:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec tau-pocket -- tau --help | head -5
|
||||||
|
```
|
||||||
|
|
||||||
|
If the Tau version banner appears, the base is good. If not, re-run the `apk` / `uv` / `uv tool install` chain and read the error.
|
||||||
|
|
||||||
|
Snapshot the base so every later session can roll back to a known-good image:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox snapshot create tau-pocket --snapshot-id tau-base
|
||||||
|
smolvm sandbox snapshot list
|
||||||
|
```
|
||||||
|
|
||||||
|
`tau-base` is now your anchor. If a later experiment breaks the sandbox, `restore` brings it back without re-installing anything.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Run a Tau session
|
||||||
|
|
||||||
|
The simplest pattern: keep `/workspace` as the working directory and let Tau read its `AGENTS.md` (project instructions) from there.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Drop an AGENTS.md describing the project before starting
|
||||||
|
smolvm sandbox file upload tau-pocket ./AGENTS.md /workspace/AGENTS.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Then either run a one-shot, non-interactive prompt:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc 'cd /workspace && tau -p "summarize the project"'
|
||||||
|
```
|
||||||
|
|
||||||
|
Or open a real interactive shell inside the sandbox:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox shell tau-pocket
|
||||||
|
# you are now root in the sandbox
|
||||||
|
cd /workspace
|
||||||
|
tau # launches the Textual TUI
|
||||||
|
```
|
||||||
|
|
||||||
|
Stop the sandbox when you're done (state is preserved on the underlying disk):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox stop tau-pocket
|
||||||
|
smolvm sandbox start tau-pocket # resume later
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Filesystem note.** `/tmp`, `/run`, and `/dev/shm` are tmpfs and **do not survive** a stop+start. Write anything that must outlive a restart under `/workspace` or `~/.tau/`. Package installs, `/etc/` edits, and `~/.tau/` itself are on the persistent overlay.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Snapshotting the learning timeline
|
||||||
|
|
||||||
|
Every time you reach a milestone worth keeping — "added the Git teacher skills", "wired compaction", "experimented with self-modification" — capture it:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# inside the sandbox
|
||||||
|
cd /workspace
|
||||||
|
git add -A && git commit -m "m1: add basic Git teacher skills" -q
|
||||||
|
tau -p "/exit"
|
||||||
|
|
||||||
|
# back on the host
|
||||||
|
smolvm sandbox snapshot create tau-pocket --snapshot-id m1-git-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
The snapshot stores the full sandbox state — installed packages, `~/.tau/`, `/workspace`, the works. The git commit is *inside* the snapshot, which is the "Git overlay" the old design document described, except you don't need to design it; the snapshot mechanism already handles it.
|
||||||
|
|
||||||
|
To rewind a failed experiment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox snapshot restore m1-git-skills
|
||||||
|
```
|
||||||
|
|
||||||
|
`restore` takes a snapshot id, not a sandbox name, which is the part that trips people up. You can list available snapshots with `smolvm sandbox snapshot list` (optionally `--json` for a machine-readable view).
|
||||||
|
|
||||||
|
A lightweight textual changelog is still useful as a human-readable index — drop it in `/workspace` so it travels with every snapshot:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# inside the sandbox
|
||||||
|
cat >> /workspace/CHANGELOG.md <<'EOF'
|
||||||
|
## m1-git-skills
|
||||||
|
- Snapshot: m1-git-skills (2026-08-06)
|
||||||
|
- Git: a1b2c3d "add basic Git teacher skills"
|
||||||
|
- Notes: oriented on Tau architecture; added teacher-mode skills.
|
||||||
|
EOF
|
||||||
|
git add CHANGELOG.md && git commit -m "changelog: m1" -q
|
||||||
|
```
|
||||||
|
|
||||||
|
Repeat per milestone. The host-side record is `smolvm sandbox snapshot list`; the in-sandbox record is `CHANGELOG.md`. Pick the one that answers your question: "what state is on disk?" → host list. "why does this state matter?" → changelog.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Importing `/teacher-mode` and an existing Tau configuration
|
||||||
|
|
||||||
|
The assumption is that `/teacher-mode` (and possibly a fully-configured `~/.tau`) already lives on the host you're importing from. There are two paths — pick one.
|
||||||
|
|
||||||
|
### 5a. `sandbox file upload` (one file or one directory at a time)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# upload a tarball (recommended for directories; smolvm file upload
|
||||||
|
# treats the source as a single file path)
|
||||||
|
tar czf /tmp/teacher-mode.tgz -C /path/to/parent teacher-mode
|
||||||
|
smolvm sandbox file upload tau-pocket /tmp/teacher-mode.tgz /workspace/teacher-mode.tgz
|
||||||
|
|
||||||
|
# then inside the sandbox
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc '
|
||||||
|
cd /workspace
|
||||||
|
tar xzf teacher-mode.tgz && rm teacher-mode.tgz
|
||||||
|
ls teacher-mode/ # confirm structure
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
Place `/teacher-mode` under `/workspace/` (or under `~/.tau/` — see 5b) so it travels with every subsequent snapshot. The default place for project-scoped resources in Tau is `.tau/` and `.agents/` relative to the cwd; `/workspace/teacher-mode` is a clean convention that mirrors the source layout.
|
||||||
|
|
||||||
|
For a custom `~/.tau` (a `catalog.toml` you've tuned, existing sessions you want to keep, a private skill set, etc.), archive and inject it the same way, but extract to the home directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# from the source host
|
||||||
|
tar czf /tmp/dot-tau.tgz -C ~ .tau
|
||||||
|
|
||||||
|
# upload + extract
|
||||||
|
smolvm sandbox file upload tau-pocket /tmp/dot-tau.tgz /tmp/dot-tau.tgz
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc '
|
||||||
|
rm -rf ~/.tau && mkdir -p ~/.tau && tar xzf /tmp/dot-tau.tgz -C ~
|
||||||
|
ls -la ~/.tau/
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Watch for:** `sandbox file upload` requires the sandbox to be running. If it isn't, the error is non-obvious — start it first or use `sandbox exec --start ...` for the extract step instead. `~/.tau` is on the persistent overlay, so once you've imported it, it survives stop/start and is captured by every snapshot.
|
||||||
|
|
||||||
|
### 5b. Mount-on-start (cleaner, when you iterate often)
|
||||||
|
|
||||||
|
If you'll be editing `/teacher-mode` on the host and want the sandbox to see changes live, pass a host path when creating the sandbox (or update an existing one):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# at create time
|
||||||
|
smolvm sandbox create --name tau-pocket --os alpine \
|
||||||
|
--mount /home/pikaos/teacher-mode:/workspace/teacher-mode \
|
||||||
|
--writable-mounts
|
||||||
|
|
||||||
|
# or update an existing one
|
||||||
|
smolvm sandbox update --name tau-pocket \
|
||||||
|
-v /home/pikaos/teacher-mode:/workspace/teacher-mode \
|
||||||
|
--writable-mounts
|
||||||
|
```
|
||||||
|
|
||||||
|
With `--writable-mounts` the host directory is read-write inside the guest. Without it, the mount is read-only — that's usually what you want for a stable skills directory.
|
||||||
|
|
||||||
|
**Same approach for `~/.tau`:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox update --name tau-pocket \
|
||||||
|
-v /home/pikaos/.tau:/root/.tau \
|
||||||
|
--writable-mounts
|
||||||
|
```
|
||||||
|
|
||||||
|
Once mounted, restart the sandbox and verify:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox stop tau-pocket
|
||||||
|
smolvm sandbox start tau-pocket
|
||||||
|
smolvm sandbox exec --name tau-pocket -- ls /workspace/teacher-mode
|
||||||
|
smolvm sandbox exec --name tau-pocket -- ls /root/.tau
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Snapshot semantics with mounts.** Anything in the mounted directory is *not* part of the sandbox disk — it lives on the host. A snapshot still captures the sandbox state, but the mount is re-attached on next start, so the *effective* content is the union of the snapshot and the current host directory. Plan accordingly: if `/teacher-mode` is the source of truth and you want a particular revision frozen inside a snapshot, copy it in (`file upload` or `cp -a`) rather than mounting it.
|
||||||
|
|
||||||
|
### 5c. Verify Tau actually picks up the skills
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc '
|
||||||
|
tau -p "list the skills you can see and which file each came from"
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
Or, if Tau has a `/skills` slash command in your build:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox exec --name tau-pocket -- tau -p "/skills"
|
||||||
|
```
|
||||||
|
|
||||||
|
If the skills aren't visible, the most common cause is the cwd: Tau reads `.tau/` and `.agents/` from the **current working directory** upward. Launch Tau from `/workspace` (or from wherever the skills directory sits) and they will be picked up.
|
||||||
|
|
||||||
|
Snapshot once `/teacher-mode` is wired in and you have a working setup:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm sandbox snapshot create tau-pocket --snapshot-id teacher-mode-ready
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Exporting the machine
|
||||||
|
|
||||||
|
This is the part that needs a clear-eyed note. "Export the machine" can mean three different things, and the right tool depends on which you want.
|
||||||
|
|
||||||
|
### 6a. Export the **state** (cheapest, most common)
|
||||||
|
|
||||||
|
This is what you usually want — the configured sandbox, with Tau installed and `/teacher-mode` in place, portable enough to bring to another host running smolvm.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# locate the snapshot on disk
|
||||||
|
smolvm sandbox snapshot list --json
|
||||||
|
# the snapshot record includes an id you can use to find the file;
|
||||||
|
# on Linux the snapshot storage lives under ~/.smolvm/sandboxes/...
|
||||||
|
# copy the whole directory tree (or a single snapshot id) somewhere portable:
|
||||||
|
|
||||||
|
cp -a ~/.smolvm/sandboxes/<id-or-vm-dir> /path/to/backup/
|
||||||
|
|
||||||
|
# or, if your build exposes `pack` (this host does NOT):
|
||||||
|
smolvm pack create --from-vm tau-pocket -o tau-pocket.smolmachine
|
||||||
|
```
|
||||||
|
|
||||||
|
The `cp -a` route is verified; the `pack` route is documented for builds that have it. On any host that has the same smolvm version and the same architecture, you can recreate the sandbox from the copied tree by pointing the new host at the snapshot id, or by using `sandbox snapshot restore` once you've registered the copied state.
|
||||||
|
|
||||||
|
> **Architecture caveat.** smolvm snapshots are tied to the guest architecture (the kernel, virtio layout, and the userland). A `firecracker` snapshot on `linux/amd64` does not move to `linux/arm64` or to macOS Apple Silicon. The substrate is portable across *compatible* hosts, not across architectures.
|
||||||
|
|
||||||
|
### 6b. Export the **workspace** (lighter, often enough)
|
||||||
|
|
||||||
|
If what you actually want to share is the project state (code, skills, changelog, sessions), export just the persistent bits — no need to ship the full VM:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# from inside the sandbox
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc '
|
||||||
|
tar czf /tmp/pocket-export.tgz \
|
||||||
|
/workspace /root/.tau /etc/profile.d 2>/dev/null
|
||||||
|
'
|
||||||
|
smolvm sandbox download tau-pocket /tmp/pocket-export.tgz ./pocket-export.tgz
|
||||||
|
|
||||||
|
# on a fresh host: create a new sandbox and import
|
||||||
|
smolvm sandbox create --name tau-pocket --os alpine
|
||||||
|
smolvm sandbox file upload tau-pocket ./pocket-export.tgz /tmp/pocket-export.tgz
|
||||||
|
smolvm sandbox exec --start --name tau-pocket -- sh -lc '
|
||||||
|
apk add --no-cache python3 py3-pip git && pip install --break-system-packages uv && uv tool install tau-ai
|
||||||
|
tar xzf /tmp/pocket-export.tgz -C /
|
||||||
|
cd /workspace && tau
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
This is what you want when the receiving host also has smolvm but a different kernel build, or when you only care about project state, not the installed system packages.
|
||||||
|
|
||||||
|
### 6c. Export the **image** (heaviest, most portable across builds)
|
||||||
|
|
||||||
|
If your smolvm build has `pack`, you can produce a single self-contained binary that boots the configured state on any compatible host:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# only if `smolvm pack` is available:
|
||||||
|
smolvm pack create --from-vm tau-pocket -o tau-pocket.smolmachine
|
||||||
|
./tau-pocket.smolmachine run -- tau -p "hello"
|
||||||
|
```
|
||||||
|
|
||||||
|
This host does **not** have `pack`; treat 6a/6b as the working path until your build exposes it. If you upgrade smolvm specifically for this, verify with `smolvm pack --help` first.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Switching the agent to Pi (or another bundled agent)
|
||||||
|
|
||||||
|
The substrate is the constant; the agent is pluggable. Two ways to switch.
|
||||||
|
|
||||||
|
### 7a. Launch a different agent in a parallel sandbox (recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# keep tau-pocket running for Tau work
|
||||||
|
smolvm sandbox create --name pi-pocket --os alpine --network nat
|
||||||
|
smolvm sandbox exec --start --name pi-pocket -- sh -lc '
|
||||||
|
apk add --no-cache nodejs npm git bash
|
||||||
|
npm i -g @mariozechner/pi-coding-agent
|
||||||
|
mkdir -p /workspace && cd /workspace && git init -q
|
||||||
|
'
|
||||||
|
smolvm sandbox exec --name pi-pocket -- pi --help | head -5
|
||||||
|
smolvm sandbox snapshot create pi-pocket --snapshot-id pi-base
|
||||||
|
```
|
||||||
|
|
||||||
|
Pi keeps its config in `~/.pi/agent/` (skills at `~/.pi/agent/skills/`), so the import dance in §5 is the same shape but with `~/.pi` as the target. Two sandboxes, two agents, one mental model.
|
||||||
|
|
||||||
|
### 7b. Use the bundled launchers for one-off sessions
|
||||||
|
|
||||||
|
smolvm ships a launcher per popular agent. These are pre-baked images with the CLI already installed — useful for quick interactive sessions, not for "the pocket" (which is a configured, skill-laden workspace).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
smolvm hermes start --name hermes-pocket # if you want Hermes for a session
|
||||||
|
smolvm claude start --name claude-pocket
|
||||||
|
smolvm codex start --name codex-pocket
|
||||||
|
smolvm pi start --name pi-quick
|
||||||
|
```
|
||||||
|
|
||||||
|
These are the same `sandbox` family under the hood; the launchers just pre-fill the install step. Once the launcher has created a sandbox, you can `sandbox exec` / `sandbox snapshot` it like any other.
|
||||||
|
|
||||||
|
> **Why not pin one agent forever?** The substrate is the constant. Tau is the primary, Pi is the alternative. Each gets its own sandbox, its own snapshot chain, and its own import of `/teacher-mode` (the skills are written in plain Markdown and travel verbatim; the only difference is where the agent looks for them — `~/.tau` vs `~/.pi/agent`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. The full "do it once" recipe
|
||||||
|
|
||||||
|
For a clean machine, this is the whole thing top to bottom:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 0. one-time check
|
||||||
|
smolvm doctor
|
||||||
|
|
||||||
|
# 1. create + install tau
|
||||||
|
smolvm sandbox create --name tau-pocket --os alpine --network nat
|
||||||
|
smolvm sandbox exec --start --name tau-pocket -- sh -lc '
|
||||||
|
apk add --no-cache python3 py3-pip git curl bash
|
||||||
|
pip install --break-system-packages uv
|
||||||
|
uv tool install tau-ai
|
||||||
|
mkdir -p /workspace && cd /workspace && git init -q
|
||||||
|
'
|
||||||
|
|
||||||
|
# 2. import /teacher-mode + ~/.tau
|
||||||
|
smolvm sandbox file upload tau-pocket /path/to/teacher-mode.tgz /workspace/teacher-mode.tgz
|
||||||
|
smolvm sandbox exec --name tau-pocket -- sh -lc '
|
||||||
|
cd /workspace && tar xzf teacher-mode.tgz && rm teacher-mode.tgz
|
||||||
|
'
|
||||||
|
|
||||||
|
# 3. snapshot the base
|
||||||
|
smolvm sandbox snapshot create tau-pocket --snapshot-id tau-base
|
||||||
|
|
||||||
|
# 4. iterate: session -> snapshot per milestone -> restore on rollback
|
||||||
|
smolvm sandbox shell tau-pocket # run tau inside
|
||||||
|
smolvm sandbox snapshot create tau-pocket --snapshot-id m1
|
||||||
|
smolvm sandbox snapshot restore m1 # if m2 broke
|
||||||
|
smolvm sandbox snapshot list # the timeline
|
||||||
|
```
|
||||||
|
|
||||||
|
That's the project. The earlier "Decision Summary" tried to design all of this from scratch; the CLI was already there.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Troubleshooting
|
||||||
|
|
||||||
|
| Symptom | Likely cause | Fix |
|
||||||
|
|---|---|---|
|
||||||
|
| `sandbox file upload` fails with no clear reason | sandbox not running | `smolvm sandbox start tau-pocket` first, or use `sandbox exec --start` |
|
||||||
|
| Tau doesn't see `/teacher-mode` skills | wrong cwd when launching | `cd /workspace` before running `tau`; Tau reads `.tau/` and `.agents/` from cwd upward |
|
||||||
|
| Packages missing after `stop` + `start` | written under `/tmp`, `/run`, or `/dev/shm` | rewrite under `/workspace` or `~/.tau/` — those are persistent |
|
||||||
|
| `sandbox snapshot restore` says "not found" | passed the sandbox name instead of the snapshot id | use `sandbox snapshot list` to get the id, then `restore <id>` |
|
||||||
|
| Two sandboxes both want to mount the same host dir | one-shot conflict | unmount the host dir from one of them, or use `file upload` instead |
|
||||||
|
| `smolvm pack` / `smolvm machine` not present | this build of smolvm | use §6a/§6b (snapshot tree copy + workspace tarball) |
|
||||||
|
| `smolvm doctor` shows swap / thp warnings | host tuning, not blocking | `sudo swapoff -a` and `echo never > /sys/kernel/mm/transparent_hugepage/enabled` if you want clean output |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. What this tutorial deliberately does **not** do
|
||||||
|
|
||||||
|
- **No custom substrate.** smolvm is the substrate. Adding a second sandbox technology re-introduces the problem smolvm already solves.
|
||||||
|
- **No custom snapshot file format.** `smolvm sandbox snapshot create` *is* the snapshot model. The earlier doc's Phase 1/2 ("Build the Base Machine", "Snapshot & Changelog Wiring") is two CLI calls.
|
||||||
|
- **No hand-rolled changelog daemon.** `smolvm sandbox snapshot list` is the host-side log. `CHANGELOG.md` inside `/workspace` is the why-we-care log. Both are optional, both are trivial.
|
||||||
|
- **No agent lock-in.** Tau is the primary; Pi, Hermes, Claude, Codex, and OpenClaw are all reachable from the same smolvm install. The pocket is the *workspace*, not the *agent*.
|
||||||
|
- **No architecture-cross-portability claim.** smolvm snapshots are architecture-bound. A `linux/amd64` snapshot is not a `linux/arm64` or macOS binary. The substrate is portable across *compatible* hosts, not all hosts.
|
||||||
|
|
@ -0,0 +1,269 @@
|
||||||
|
> **⚠️ 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
|
||||||
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue