projects turingos

TuringOS

In development

An agentic execution layer from uncoalesced, built on Debian. It runs Claude Code agents in throwaway sandboxes, and nothing touches your real project until you have read the diff and approved the merge.

Bash · Btrfs · Rust · Debian live ISO · MIT

$ turingos agent start ~/api "Refactor auth and run tests"

Creating agent sandbox...
  Project   /home/you/api
  Backend   btrfs

✓  Original project protected
✓  Sandbox created
✓  Agent started (PID 48213)
Example terminal session: starting an agent task creates a sandbox first, protecting the original project, then launches Claude inside it.

Demo

Walkthrough of the v1.2 desktop UI: pick a project with @, describe the task, and it runs as a Claude Code task in a sandbox. 24 seconds, no sound.

01 · the idea

Full autonomy inside the sandbox. A human at the gate.

TuringOS is not a Linux distribution with Claude preinstalled. It is a different execution model for autonomous agents. Normally a person drives a terminal, the terminal runs a program, and the program writes to the disk. When the thing at the keyboard is an agent, that last step is where it gets uncomfortable.

So TuringOS puts a policy layer between the agent and the filesystem. Every task runs in an ephemeral copy of the project, where the agent can do whatever the task needs. Before anything becomes permanent, a person reads the diff and chooses.

the usual model

  1. Human
  2. Terminal
  3. Program
  4. Filesystem

turingos

  1. Youa task in plain language
  2. Claude agentClaude Code, run headless
  3. TuringOS policy layerthe Bash control plane
  4. ephemeral sandbox · full autonomy

    1. Btrfs snapshotcopy-on-write clone of the project
    2. Filesystemedits, builds, tests
  5. Diff + human approvalthe gate
  6. Merge, or roll backyour real project

The Bash layer is the product. It orchestrates things Linux already does well (Btrfs snapshots, git, renice, ionice) instead of reinventing them.

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, because Btrfs snapshots are copy-on-write. 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 next to the sandbox, not inside it (source project, backend, task, timestamp), so every later command knows where the changes came from and where they go back to, and the agent can’t redirect a merge by editing it.
  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

Begin the task now.

The review screen reads that test-result file for its pass or fail line. The agent writes the file itself, so it is a report to check, not proof.

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 sandbox, the project, when the sandbox was created and its backend, then one line with the total files and lines changed, every file marked modified, added or deleted, and the test result. Then it asks.

Sandbox Diff Inspector

  Task      Refactor auth and run tests
  Sandbox   auth-refactor-1027
  Project   ~/code/webapp
  Created   2026-10-27 14:02
  Backend   btrfs

  2 files changed   +109   -67

    M  auth/session.py
    M  tests/test_auth.py

✓  Tests: 14/14 passed

What would you like to do?
  [ M ] Merge changes into project
  [ R ] Rollback — discard all changes
  [ V ] View full diff
  [ S ] Save diff to file
  [ Q ] Quit (keep sandbox)
Example diff inspector output: the sandbox details, a total of files and lines changed, each changed file, the test result, and a menu to merge, roll back, view the full diff, save it, or quit.

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.

Everything leaves a trail

Each state change writes one line to ~/.turingos/logs/audit.log: SANDBOX_CREATE, AGENT_START, AGENT_COMPLETE, AGENT_STOP, SANDBOX_MERGE, SANDBOX_ROLLBACK, BAZAAR_INSTALL, GAME_MODE_ON and their counterparts, with the details of what was touched.

04 · the desktop

An assistant layer you can see

The ISO boots straight into a fullscreen desktop shell: a web page in a Brave app window, with a small Rust desktop service behind it. It is the part people see: a menu bar, a clock and greeting, and one composer that asks “What do you want to cook?”

Chat or task: the project decides

A message with no project attached is a plain question, answered inline with one Claude call. No sandbox, no agent. Type @ to attach one of your git repositories and the same message becomes a real Claude Code task, run through turingos agent start in a sandbox. There is no separate mode to switch.

Live state

Corners show the agent (idle, working, agentic) and its task, the sandbox, Game Mode, CPU and memory, read from ~/.turingos, checked every second and sent only when something changed.

Model picker

Pick the Claude model and effort level per message, remembered locally.

The dock

Hidden until the cursor reaches the bottom edge, magnifying toward it on a real mass-spring-damper, launching real system apps.

Side panel

Your pull requests and review requests via gh, and your next calendar event via real Google sign-in, with an honest empty state instead of sample data.

Clawd

A small pixel mascot that patrols near the dock. Shake the cursor to ask it a one-off question.

Read-only by design

The UI reads ~/.turingos and never writes system files. The page never touches the system: the desktop service, turingosd, does, behind a local bridge, and hands the page one snapshot at a time.

05 · around the agent

Tools in, priority down, spend visible

Clawd Bazaar

A terminal registry of MCP servers. turingos bazaar opens a fuzzy finder, and turingos bazaar install <tool> installs one and registers it with Claude Code in ~/.claude.json. It ships with five as a bundled fallback, all from the official modelcontextprotocol/servers repository: GitHub, Filesystem, Postgres, Brave Search and Memory. The plan said to ship two or three that genuinely install rather than claim hundreds, and that held.

The bazaar also has a standalone home, turingos-bazaar: a curated registry of MCP servers, a zero-dependency CLI (mcp-bazaar) and a browseable web catalogue. One command installs a server into Claude Code, Cursor, Windsurf, Continue or Cline, and it works without TuringOS. It is packaged for npm as turingos-bazaar but not published there yet.

Game Mode

turingos game on finds agent and build processes (Claude, Node, Python, Cargo, Make and the like) and lowers their priority for both CPU and disk. Agents keep working in the background and a notification fires when the task finishes. turingos game watch checks every five seconds for Steam, Lutris, Heroic, Wine or Gamescope and switches itself on and off. game off restores the processes it changed; any that need root to restore keep low priority until they restart.

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

It does not touch the kernel scheduler. It orchestrates what the system already has.

System monitor

One HUD for GPU VRAM, CPU load, RAM, the active agent’s PID and sandbox, and API token spend. turingos monitor spend totals input and output tokens from the agent’s own logs and gives a rough cost estimate.

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:

HookWhat it does
0200-trimRemoves LibreOffice, printing, Bluetooth and unused GPU drivers (about 1 GB)
0300-locale-trimStrips locale data, man pages and docs (about 200 MB)
0400-install-turingosChecks the staged install, adds gum and the launcher entry
0420-install-braveInstalls Brave from its signed apt repository as the default browser, with the Claude extension installed and pinned by policy
0450-build-daemonBuilds the desktop service, turingosd, against the image’s libraries, then removes the toolchain
0470-autologin-kioskLogs straight into the desktop, ordered after live-config
0490-install-homebrewInstalls Homebrew for the live user
0495-installerAdds the Calamares installer, so the live system can be installed to disk
0500-install-claude-cliInstalls Claude Code (native installer, npm fallback) and OpenCode
0900-boot-timeoutBoot menus start the live entry after 3 seconds
0910-persistence-menuAdds a live-with-persistence boot entry

You can also skip the ISO entirely: the CLI runs on any Linux with Bash 4 and the tools listed under “run it” below.

07 · what does not work yet

What is still open, honestly

These are all written down in the repository, and they stay on this page until fixed. The UI not starting on boot, which used to head this list, is fixed: the image now logs in by itself and opens the UI fullscreen.

  • 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 effort setting doesn’t reach agents. The model you pick is passed to Claude agents; effort only applies to chat answers so far.
  • 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 on real hardware. The mic button records on the machine and transcribes with local Whisper, but it hasn’t been tried with a real microphone on the ISO. With no microphone at all, it records silence instead of saying so.
  • Some installs are untested. BIOS installs, Secure Boot, and Raspberry Pi and BIOS boot on arm64 haven’t been tested yet, and the installer’s “Erase disk” option makes a swap partition as large as your RAM.
  • OpenCode is large. At about 730 MB unpacked, it is the biggest single item in the image.

08 · run it

The CLI needs no VM

You need Bash 4 or later, git, jq, rsync, curl and the claude CLI, plus btrfs-progs for snapshots on a Btrfs disk; anywhere else, sandboxes fall back to rsync. gum and fzf make it nicer, and libnotify adds desktop notifications.

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.

contributors

Built by three people

TuringOS is an independent open-source project. It is not made, endorsed or supported by Anthropic. Claude and Claude Code are Anthropic’s products, and TuringOS runs them as the agent.