TuringOS

02 · the sandbox

A copy-on-write snapshot, made before the agent starts

turingos agent start does five things, in this order, and stops if any of them fails:

1. Snapshots the project with btrfs subvolume snapshot. It is instant and takes no extra space until files change. On a disk that is not Btrfs it falls back to an rsync copy, and copies .git across so the diff still works.
2. Writes a small metadata file into the sandbox (source project, backend, task, timestamp) so every later command knows where the changes came from and where they go back to.
3. Writes the task prompt into the sandbox.
4. Launches Claude Code inside the sandbox, headless (--print, --output-format stream-json), in the background, logging everything.
5. Records the start in an audit log and, when the agent exits, fires a desktop notification.

This is the prompt the agent receives, verbatim apart from the placeholders:

You are running inside a TuringOS agent sandbox.

Sandbox path: <sandbox>
Task: <your task>

Instructions:
- Work only within this sandbox directory
- Make your changes, then run any applicable tests
- Write test results to: <sandbox>/.turingos_test_result
  Format: "<N> passed, <M> failed"
- When complete, summarize what you changed

The test-result file is how the review screen can say whether the tests passed without trusting the agent’s summary of its own work.

03 · the review

Nothing is merged until you say so

When the agent finishes, turingos sandbox diff opens the diff inspector. It shows the task, the backend, a git summary of what changed, every file marked modified, added or deleted with its line counts, the test result, and for Btrfs the snapshot’s UUID and creation time. Then it asks.

Sandbox Diff Inspector

  Task      Refactor auth and run tests
  Backend   btrfs

  2 files changed   +109   -67

    M  auth/session.py          +88 / -54
    M  tests/test_auth.py       +21 / -13

✓  Tests: 14/14 passed

What would you like to do?
  [ M ] Merge changes into project
  [ R ] Rollback — discard all changes
  [ V ] View full diff (git patch)
  [ S ] Save diff to file
  [ Q ] Quit (keep sandbox)

Merge applies the sandbox to the original project, and asks twice: once before applying, once before destroying the sandbox. Rollback deletes the snapshot and the original is exactly as it was. Quit leaves the sandbox where it is, so a review can wait.

04 · the desktop

An assistant layer you can see

The ISO boots into an Electron shell, fullscreen. It is the part people see: a menu bar, a clock and greeting, and one composer that asks “What do you want to cook?”

05 · around the agent

Tools in, priority down, spend visible

renice -n 10 -p $PID     # CPU: step back
ionice -c 3 -p $PID      # disk: idle class only

06 · the image

A bootable Debian live ISO

The whole thing ships as a Debian Trixie live image built with live-build, with the UI and all the tooling preinstalled. The build hooks run in this order:

You can also skip the ISO entirely: the CLI runs on any Linux with Bash 4, git and jq, and there is an Arch/CachyOS package.

07 · what does not work yet

The v1 test build, honestly

These are all written down in the repository, and they stay on this page until fixed.

• The UI does not start on boot. The ISO lands on a login screen instead of the fullscreen UI, and the UI only appears if you launch it by hand. The binary works; the autologin and autostart path does not. The known issues file lists the likely causes and five fixes to try.
• Merge, rollback and stop are terminal-only. They ask a yes or no question in the terminal, so the UI cannot call them until they get a non-interactive flag.
• The model picker is wired on one side. The UI passes the chosen model and effort to the agent, but the agent script does not read them yet.
• The permission sheet, task view and notifications with Undo are designed and specified, not built. For now, merge and rollback are the approval.
• Dictation is unverified offline. The mic button uses Chromium’s speech API, which needs a speech backend the offline image may not have.
• The live image’s login is undocumented. It uses live-config’s default account, and nothing in the build says so yet.

08 · run it

The CLI needs no VM

You need git, jq and the claude CLI; gum and fzf make it nicer. Snapshots need btrfs-progs and a Btrfs disk, and everything else falls back to rsync.

git clone https://github.com/uncoalesced/TuringOS turingos
cd turingos && chmod +x turingos
./turingos init

./turingos agent start /path/to/project "Refactor auth module and run tests"
./turingos sandbox diff

The full command list, the ISO build and the end-to-end workflow guide are in the repository. It is MIT licensed.