ijuanes e0a871523a Tutorial y tutorial desactualizado.

2026-08-23 15:45:29 +01:00

12 KiB

Raw Blame History

⚠️ 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, 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.

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.¹²³⁴⁵

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.²⁵¹ 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.³⁴⁵

Key properties:

Tau is a minimalist terminal coding agent that reads files, edits code, runs commands, and maintains durable session history.⁴⁶³
smolVM packs a Linux VM into a single portable file (.smolmachine) with sub‑200ms cold boot and hardware isolation per workload.⁷⁸¹²
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.⁸⁵¹²

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:⁶³⁴

tau_ai: provider‑neutral event stream from any supported language model endpoint.³⁴⁶
tau_agent: portable agent “brain” (messages, tools, events, loop, harness, sessions).⁴⁶³
tau_coding: terminal application (CLI/TUI) with file/shell tools, skills, prompts, and on‑disk sessions.⁹³⁴

This project treats Tau as:

The only agentic framework.
Both a working coding assistant and an educational blueprint for agent architecture.⁹⁶³⁴

Single Runtime Substrate: smolVM

smolVM is a CLI tool to build and run portable, lightweight, self‑contained VMs:¹²⁷⁸

Sub‑second (often <200ms) cold boot times.²⁷⁸¹
Each workload gets its own kernel boundary, not just container namespaces.⁷⁸¹²
A stateful VM can be packed into one .smolmachine file that runs anywhere the architecture matches.¹⁰⁸¹²⁷

This project uses smolVM as the only sandbox substrate:

No containers, no other hypervisors, no filesystem snapshots.⁵

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.⁶³⁴
- A /workspace directory for code, skills, curricula, and logs.⁵¹²

Creation flow (coarse‑grained snapshot):

Run Tau inside a smolVM machine until a learning milestone or stable state is reached.
Stop the machine (or flush state to disk).
Pack or copy the VM as a .smolmachine using smolVM’s pack or machine commands.¹⁰¹²
Save the artifact under a meaningful name, e.g. tau-sandbox-m1.smolmachine.⁵

Restoration flow:

On any supported host, run smolVM against the chosen .smolmachine.
Tau starts inside the VM, seeing exactly the same environment and /workspace state as at snapshot time.⁸¹²
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:³⁴⁵

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.¹¹³⁵

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.⁹⁶
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).⁴³⁹

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”).⁵
For each snapshot restore:
- Timestamp.
- Snapshot ID restored.
- Reason (“Replay intro module”, “Roll back broken experiment”).⁵

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:¹²⁸

Use smolvm machine run or smolvm pack create to derive a base environment from a standard image (e.g. python:3.12-alpine).²⁸¹⁰¹
Inside the VM, install Tau via uv tool install tau-ai.⁶³⁴
Create /workspace and initialize a Git repo if desired.
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:

Start a smolVM machine from tau-sandbox-base.smolmachine or a derived snapshot (e.g. tau-sandbox-m1.smolmachine).⁸¹²⁵
Run Tau from /workspace, connecting it to a language model provider via Tau’s /login mechanism.³⁴⁹
Use Tau’s tools and skills to explore, edit, and run code; logs and session exports remain inside the VM.⁴⁶³

3. Create a Snapshot

When a meaningful state is reached:

Ensure /workspace is consistent (optional: run tests, lint).
Stop the machine or persist state.
Use smolVM to pack or copy the VM into tau-sandbox-mN.smolmachine.¹⁰¹²⁸
Inside /workspace:
- Commit any promoted changes to Git.
- Append a changelog entry describing the snapshot.⁵

4. Restore a Snapshot

To revisit a previous milestone:

Pick the desired .smolmachine file.
Start a new machine from that artifact.
Run Tau; it sees the restored /workspace and Git state.
Append a restore event to the changelog to keep the timeline coherent.⁵

Roadmap (Minimal Version)

Phase 1 – Base Tau Machine

Install smolVM on a supported host.¹²⁸
Build tau-sandbox-base.smolmachine with:
- Linux image.
- Python + uv.
- Tau installed (uv tool install tau-ai).⁶³⁴
- 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.⁵

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.⁹³⁴
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.²¹³⁴⁵ ¹²¹³¹⁴¹⁵¹⁶¹⁷

⁂

12 KiB Raw Blame History Unescape Escape