TuringOS

An agentic execution layer built on Debian. It runs Claude Code agents in safe sandboxes and comes with a live desktop UI, an MCP tool registry, and Game Mode.

Download the ISO (amd64) · SHA-256 · All releases

---

What it is

TuringOS wraps Claude Code in a policy layer between the agent and your filesystem. Every agent task runs inside an ephemeral Btrfs snapshot, and nothing touches your real project until you review a diff and approve the merge.

You
 ↓
Intent (natural language task)
 ↓
Claude Agent
 ↓
TuringOS Policy Layer
 ↓
Ephemeral Btrfs Sandbox
 ↓
Filesystem
 ↓
Diff + Human Approval
 ↓
Merge

We ship it as a bootable Debian live ISO with the UI and all tooling pre-installed.

Download

Latest release: TuringOS 1.2.

Image	Checksum
live-image-amd64.hybrid.iso	.sha256
live-image-arm64.hybrid.iso	not published for 1.2 yet

Check the amd64 image before booting it:

sha256sum -c live-image-amd64.hybrid.iso.sha256

The 1.2 release has no .sha256 for arm64, so compare sha256sum live-image-arm64.hybrid.iso against a hash from a maintainer until one is published. The arm64 image boots on Apple Silicon through UTM.

Boot it in a VM (VMware, VirtualBox, QEMU: 4 GB RAM, 2 CPUs, EFI or BIOS) or write it to a USB stick. It logs in by itself and opens the TuringOS UI fullscreen. Brave is the default browser and comes with the Claude extension, so claude → /login, the Anthropic Console (API keys) and Google sign-in open right there. Homebrew is ready too: brew install <formula>.

The live session runs from RAM: a reboot forgets logins, keys and installs. To keep them, click Install in the dock (or search "Install TuringOS" with Ctrl+K). The Calamares installer partitions the disk, creates your account (which logs in automatically, like the live session) and installs GRUB for BIOS or UEFI. It works offline. Give the VM or machine a disk of 20 GB or more.

Debug login: user / live.

Why it exists

TuringOS is built for AI-first consumer hardware: a laptop, tablet, or phone whose whole job is working with Claude. You boot straight into Claude. The agent sandbox is the environment, not an app you open, and help is always one cursor shake away. We want a distro that a hardware maker could put on a Claude-dedicated device and ship.

It also runs on hardware without a cloud connection. If the device has a decent GPU, you can point TuringOS at a local model and keep working (see Models).

Known issues

• BIOS installs and Secure Boot haven't been tested yet.
• Raspberry Pi bootloaders and BIOS on arm64 haven't been tested yet.
• The installer's "Erase disk" option makes a swap partition as large as your RAM.
• TuringOS is a work in progress. Please file what breaks.

---

Preview

Walkthrough of the v1.2 desktop UI.

---

Features

Btrfs agent sandboxing

The agent works in an instant copy-on-write snapshot of your project, isolated from the original. You see every change before anything becomes permanent, and one keystroke merges or rolls back.

Clawd Bazaar

A terminal registry of MCP tools. You can browse tools, install them, and register them with Claude Code (~/.claude.json) with one command. It ships with GitHub, Postgres, Filesystem, Brave Search, and Memory servers.

Game Mode

When you launch a game, TuringOS drops agent and build processes to low priority. Agents keep working in the background, and you get a notification when the task finishes.

Live desktop UI

A desktop shell (a web page in a Brave app window, served by the trust stack's bridge, with a small Rust desktop service behind it) that shows agent state, sandbox status, system stats, and MCP connections in real time. It launches fullscreen on boot. The mic button dictates into the composer with local Whisper (the model downloads on first use), or with Wispr Flow via turingos voice wispr-import (unofficial, opt-in). The image ships Brave as its browser: links and Google sign-in open there, and being Chromium-based it runs the Claude in Chrome extension.

Models

Claude is the default. You can also run agents on open models through OpenCode:

turingos model set nvidia                                # NVIDIA NIM: pick models, backups, API key
turingos model set ollama "" llama3.2                    # local Ollama (default http://localhost:11434)
turingos model set openrouter "" meta-llama/llama-3.3-70b-instruct   # needs OPENROUTER_API_KEY
turingos model set custom http://localhost:8080 my-model # any OpenAI-compatible server
turingos model set claude                                # back to Claude
turingos model status                                    # show provider, ping endpoint

For a non-Claude provider, turingos agent start runs opencode run --model <provider>/<model> inside the sandbox instead of claude. The live ISO ships OpenCode; install Ollama yourself, since its GPU libraries are too big for the image:

curl -fsSL https://ollama.com/install.sh | sh

For ollama and custom, TuringOS writes the OpenCode provider config itself (~/.turingos/opencode-<provider>.json, pointed at <endpoint>/v1), so nothing needs adding to your opencode.json. Put OPENROUTER_API_KEY in ~/.turingos/config.env or your shell. TuringOS unsets it for every other provider before launching OpenCode, and model status only sends it to OpenRouter.

NVIDIA NIM

turingos model set nvidia (also offered during turingos init) sets up NVIDIA's hosted models:

1. Pick the models you want from a curated list of text, code and vision models (Nemotron, Kimi, GLM, DeepSeek, gpt-oss, Gemma, Mistral, Codestral, Llama Vision and more). You can also type any other model ID from build.nvidia.com.
2. Choose a default model and up to 3 backups. If the default fails, turingos agent start tries each backup in order and only reports an error once all of them have failed.
3. Choose the image model for turingos image (FLUX.1 dev or schnell).
4. Paste your API key (nvapi-..., free at build.nvidia.com). It's saved as NVIDIA_API_KEY in ~/.turingos/config.env, readable only by you.

turingos model use moonshotai/kimi-k3                    # switch the default model
turingos image "a lighthouse at dusk, oil painting"      # saves image-<time>.jpg
turingos image "app icon, flat style" icon.jpg

TuringOS points OpenCode at your picked models with its own config file (~/.turingos/opencode-nvidia.json), so your opencode.json stays untouched. NVIDIA_API_KEY is unset for every other provider.

System monitor

One HUD for GPU VRAM, CPU load, RAM, the active agent PID, the sandbox name, and API token spend.

---

Repo structure

turingos/
├── turingos                  # main CLI entrypoint
├── core/
│   ├── config.sh             # paths, state, PID files
│   ├── ui.sh                 # terminal UI primitives
│   ├── logging.sh            # leveled logging + audit trail
│   └── init.sh               # `turingos init`
├── agent/
│   ├── claude.sh             # start / stop / status / logs
│   ├── model.sh              # providers, `turingos model`, OpenCode configs
│   └── nim.sh                # NVIDIA NIM picker + `turingos image`
├── sandbox/
│   ├── btrfs.sh              # create / merge / rollback
│   └── diff.sh               # diff inspector + action menu
├── bazaar/
│   ├── registry.json         # MCP tool registry
│   ├── registry.sh           # browse / search / info
│   └── install.sh            # install + register with Claude Code
├── game/
│   └── gamemode.sh           # renice / ionice + auto-detect
├── monitor/
│   └── system.sh             # GPU / CPU / RAM / agent HUD
├── voice/                    # `turingos voice` + Wispr Flow helper
├── ui/                       # desktop shell: the page (web/: css/, js/)
├── daemon/                   # turingosd, the desktop service behind the bridge
├── assets/                   # branding, palette, UI preview media
├── pkg/                      # Claude CLI installer, persistence setup, first-run banner, ISO docs
├── debian-live/              # Debian live-build config + hooks
│   ├── sync-scripts.sh       # stage the install into includes.chroot
│   └── config/
│       ├── hooks/normal/     # build-time hooks (trim, install, UI build, kiosk, boot menus)
│       └── package-lists/    # explicit apt package list
├── arm/                      # arm64 ISO build + QEMU test scripts
├── tests/                    # bash regression tests (run in CI)
├── WORKFLOW.md               # end-to-end usage guide
└── plan.md                   # architecture + build plan

---

Quick start (CLI only)

Requires: git, jq. Optional but recommended: gum, fzf.

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

Set your API key when prompted, then:

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

When the agent finishes:

./turingos sandbox diff

Choose merge, rollback, or view the full patch.

---

Build the ISO (Debian live)

Requires a Debian Trixie machine with live-build installed.

# Install live-build
sudo apt install live-build

# Clone the repo
git clone https://github.com/uncoalesced/TuringOS
cd TuringOS

# Stage TuringOS + the UI source into the image
./debian-live/sync-scripts.sh

# Build (takes 20–40 min, needs internet: crates, Brave, Homebrew, Claude Code, OpenCode)
cd debian-live
sudo lb config --distribution trixie --architectures amd64 \
    --archive-areas "main contrib non-free-firmware"
sudo lb build

The ISO lands in debian-live/live-image-amd64.hybrid.iso. Boot it in a VM or write it to USB with:

sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress

On first boot the UI launches fullscreen. Open a terminal and run turingos init to configure your API key.

Architectures: amd64 (above) and arm64 — build the arm64 image with ./arm/build.sh; it has the exact same feature set.

Persistence: like Kali, the boot menu offers a Live system (persistence) entry. Prepare the stick once — it adds an ext4 partition labelled persistence in the disk's free space:

sudo ./pkg/make-persistence.sh /dev/sdX

then pick that entry when booting: files you change (including ~/.turingos and your API key) survive reboots. The plain entry stays ephemeral.

Full build instructions: pkg/ISO_BUILD.md

---

CLI reference

turingos agent start [project] [task]   Start Claude in a sandbox
turingos agent stop                     Stop the running agent
turingos agent status                   Show agent state
turingos agent logs                     Tail agent output

turingos sandbox create [project]       Create sandbox
turingos sandbox diff                   Review what the agent changed
turingos sandbox merge                  Apply changes to original project
turingos sandbox rollback               Discard sandbox

turingos bazaar                         Browse MCP tools (fzf UI)
turingos bazaar install <tool>          Install + register with Claude Code
turingos bazaar installed               List installed tools

turingos game on                        Deprioritize agents for gaming
turingos game off                       Restore priorities
turingos game watch                     Auto-detect game launches

turingos status                         System + agent HUD
turingos monitor watch                  Live refreshing dashboard
turingos monitor spend                  API token usage + cost estimate

turingos model status                   Show model provider + ping endpoint
turingos model set <provider> [endpoint] [model]
                                        claude | nvidia | ollama | openrouter | custom
turingos model use <model>              Change the default model
turingos image "<prompt>" [out.jpg]     Generate an image with NVIDIA FLUX

turingos voice                          Show the speech-to-text backend
turingos voice backend whisper|wispr    Pick local Whisper or Wispr Flow

turingos init                           First-time setup
turingos dashboard                      Interactive menu
turingos help                           Full command list

---

ISO hook execution order

Hook	What it does
0200-trim	Purges LibreOffice, CUPS, Bluetooth, unused GPU drivers (~1GB)
0300-locale-trim	Strips locale data, man pages, docs (~200MB)
0400-install-turingos	Checks the staged install, adds gum and the launcher entry
0420-install-brave	Brave from its signed apt repo as the default browser (xdg-open, x-www-browser, $BROWSER), Claude extension installed and pinned by policy
0450-build-daemon	Builds the desktop service (turingosd) against the image's libraries, then removes the toolchain
0470-autologin-kiosk	lightdm autologin into openbox, ordered after live-config
0490-install-homebrew	Homebrew in /home/linuxbrew/.linuxbrew, owned by the live user, on PATH
0495-installer	Calamares installer (TuringOS branding, turingos-install launcher, autologin + Homebrew handed to the new account)
0500-install-claude-cli	Installs Claude Code (native installer, npm fallback) and OpenCode
0900-boot-timeout (binary)	Boot menus default to the live entry after 3 seconds (isolinux + GRUB)
0910-persistence-menu (binary)	Adds the Kali-style Live system (persistence) boot entry (isolinux + GRUB)

---

Requirements

Runtime (CLI)

Dependency	Required	Purpose
bash 4+	Yes	Shell runtime
git	Yes	Sandbox diff/merge
jq	Yes	State, MCP config, registry
btrfs-progs	Yes (Btrfs)	CoW snapshots
rsync	Yes	Sandbox copy, diff and merge
curl	Yes	Model endpoints, installers
claude CLI	Yes	Agent execution
gum	Recommended	Interactive UI
fzf	Recommended	Fuzzy search
libnotify	Optional	Desktop notifications

Build (ISO)

• Debian Trixie host
• live-build
• Internet access during build (Rust crates, Brave, Homebrew, Claude Code, OpenCode)

---

License

MIT. See LICENSE.