Theseus
Oefen installeren, upgraden, terugdraaien en verwijderen in wegwerpcontainers, en bewaar het bewijs.
Theseus (Θησεύς) is de held die het labyrint in ging en er weer uit kwam door de draad van Ariadne te volgen. Deze volgt een tool door zijn levenscyclus en houdt de draad van bewijs vast waarmee je terugvindt wat er veranderde.
- Rust
- Ratatui
- Docker
- MCP
- Claude Code
GitHub (opent in een nieuw tabblad)README (opent in een nieuw tabblad)Changelog (opent in een nieuw tabblad)
Op deze paginaInstalleren is het makkelijke deel
Installeren is het makkelijke deel
De meeste installatietests houden op bij een schone installatie op een verse machine. De lastige vragen komen daarna. Blijven de gegevens van de gebruiker staan na een upgrade? Breekt een herinstallatie de configuratie? Wat gebeurt er als een upgrade halverwege wordt afgebroken? Kom je met terugdraaien weer bij een versie die werkte? En welke bestanden staan er na het verwijderen nog?
Theseus speelt die levenscyclus na in wegwerpcontainers met Linux die het zelf aanmaakt en beheert. Een recept beschrijft de stappen voor installeren, configureren, upgraden, onderbreken, downgraden, terugdraaien en verwijderen, en de controles die na elke stap moeten kloppen. Elk gekozen profiel en scenario draait in een nieuwe container. Het bewijs blijft bewaard: opdrachten, afgeschermde logs, vingerafdrukken van bestanden, uitkomsten van controles en achtergebleven bestanden die een maintainer moet beoordelen.

De schermafbeeldingen komen uit voorbeeldruns en zijn gemaakt met het screenshotscript van de repository.
Aan de slag
Theseus is pre-release. Je hebt een actuele stabiele Rust-toolchain nodig, de Docker-CLI en een bereikbare Docker-daemon. De controller draait op Linux, macOS of Windows; de gasten zijn Linux-containers.
cargo install --git https://github.com/AraneaDev/theseus --locked theseus
theseus --helpHet programma theseus komt in de bin-map van Cargo, meestal ~/.cargo/bin. De voorbeelden staan in de repository, dus clone die om het losstaande voorbeeld te proberen. Het installeert echte shellprogramma's in versie 1 en 2, configureert ze, controleert hun identiteit en bewaarde gegevens en verwijdert ze weer:
git clone https://github.com/AraneaDev/theseus.git
cd theseus/examples/standalone
docker pull ubuntu:24.04
theseus validate
theseus # preview first; press r to run
theseus run --headless --profile user --scenario cleanTheseus haalt geen images op tenzij je run --pull meegeeft, en legt per run vast welke onveranderlijke image-ID is gebruikt. De run meldt waar het rapport staat. Dat open je later opnieuw, ook zonder Docker:
theseus report .theseus-runs/RUN_ID
theseus report .theseus-runs/RUN_ID --json
theseus cleanup .theseus-runs/RUN_IDMet theseus init krijg je een beginrecept voor je eigen tool. De opdrachten daarin falen bewust totdat je ze vervangt.
De werkbank
theseus zonder argumenten opent een voorvertoning, geen run. Je ziet de gekozen profielen en scenario's, de vaste omgeving in de gast en de opdracht van elke stap. Met p en s wissel je van profiel en scenario, en er gebeurt niets tot je op r drukt.

Druk in een onaangeroerde voorvertoning op e om het recept als ruwe TOML te bewerken. Ctrl-T valideert het concept en Ctrl-S slaat het op als nieuw bestand naast het origineel. De editor overschrijft nooit een bestaand bestand, slaat niets automatisch op en start zelf geen run.
Tijdens een run toont de kop het lopende scenario, de stap en de verstreken tijd, terwijl afgeronde stappen de lijst vullen.

Lopende en opgeslagen rapporten gebruiken dezelfde weergave: stappen, bevindingen, bestanden, opdrachten en logs. Een opgeslagen rapport opent op de eerste stap die aandacht vraagt. Met f en F spring je tussen probleemstappen, / filtert het bewijs en y kopieert het gekozen record. ? toont alle toetsen voor de huidige modus. Muisbediening zet je aan met --mouse, want een terminal die de muis vangt, laat je geen tekst meer selecteren.
Vergelijkingen, plugins en MCP-controles
Een vergelijkingssuite haalt meerdere installatiemethoden, of meerdere echte image-ID's, door dezelfde engine en vergelijkt de opgegeven bestandsgebieden. Elke variant krijgt nieuwe containers. Vanuit de root van de repository:
theseus compare --suite examples/comparisons/methods.toml --headlessTwee recepttypen zijn bedoeld voor agenttooling. Een pluginlevenscyclus installeert, updatet, schakelt uit, schakelt in en verwijdert een lokale Claude Code-plugin in de gast, met een inventariscontrole op elk ijkpunt. Een MCP-levenscyclus oefent de registratie van een andere server bij een client met een vaste versie, en controleert de identiteit en de toollijst van die server. Allebei gebruiken ze een clientprogramma dat je zelf expliciet aanlevert. Theseus zoekt of start nooit een client op je eigen machine.
Gebruik vanuit een agent
theseus serve stelt dezelfde engine beschikbaar aan een MCP-client via gewone stdin en stdout. Er zit geen model achter en er gaat geen netwerkpoort open. Beide roots zijn verplicht:
theseus serve --project-root /absolute/project --output-root /absolute/evidence --max-run-seconds 3600| Tool | Doel |
|---|---|
recipe_inspect | Een recept bekijken en opgeschoonde records per pagina lezen. |
run_start | Een selectie toelaten die aan de digest van het recept vastzit. |
run_list | De toegelaten runs van dit serverproces tonen. |
run_status | De bewaarde status opvragen of het opgeslagen bewijs verversen. |
run_cancel | Annulering van een toegelaten run aanvragen. |
run_evidence | Opgeslagen records en ruwe logbytes per pagina lezen. |
Een recept bekijken of bewijs lezen bereidt nooit Docker voor en voert niets uit. Een toegelaten run is nog geen geslaagde run: de client vraagt de status op tot de run klaar is en leest dan de uitkomst.
Wat het bewijs wel en niet zegt
Elk resultaat geldt alleen voor de controles en waarnemingen die het recept opgeeft. Ook een geslaagde run kan bestanden noemen waar een mens over moet beslissen. Theseus toont die bevindingen naast de uitkomst en verstopt ze niet achter een groen vinkje. Logs en vergelijkingen hebben een grens, en als een opname is afgekapt, staat dat in het rapport.
Opruimen verwijdert alleen wat in het journaal van de run staat en het eigendomslabel van Theseus draagt. Er is geen globale Docker-prune, en Theseus past je daemoninstellingen of gebruikersgroepen niet aan.
De grenzen zijn bewust gekozen:
- Een container is geen sandbox voor kwaadaardige code. Recepten zijn bedoeld voor invoer die de maintainer zelf in de hand heeft.
- Een onderbreking is het abrupt stoppen van de hele container op een opgegeven pauzepunt. Het zegt niets over stroomuitval op de host, fsync-gedrag of willekeurige volgordes binnen een installer.
- Native doelen via de native helper zijn gemerged en slagen in de native CI op Linux, macOS en Windows. Acceptatie op echte aangeleverde machines via SSH, het resetten van een VM en interactieve desktopsessies staan nog open.
Status
Theseus is pre-release; de eerste release met een tag wordt 0.0.1. Voor acceptatie van een release moet dezelfde broncode slagen in de native jobs voor Linux, macOS en Windows en in alle Docker-suites voor Linux. De roadmap houdt bij wat af is en wat nog openstaat. In de documentatie vind je de receptreferentie, de afspraken over bewijs en de handleiding voor herstel.