Torio

Thin control plane · macOS and Linux

Agents need context.
Credentials need a boundary.

Torio creates a Linux VM, runs Claude Code or Codex inside it, attaches the repositories you name, and keeps a private Markdown vault the agent can search. Host Git and provider credentials stay outside the VM. Private SSH reads use a guest-generated deploy key, MCP OAuth belongs to a separate guest identity, and operator Git write capability exists only inside a session you open.

Get startedSee how it fits together

The pieces, and who owns them

Torio is not the AI, not the VM, and not the chat window. It is the layer that brings those three into a known-good state and then gets out of the way. One VM runs one agent identity: --backend names the agent and Torio finds its box, so a second backend means a second VM rather than two identities contending over the same checkouts.

Inside the box the agent runs without permission prompts, and that inversion is the point. A prompt is a control inside the agent's own process: it can be ignored, and in practice it is clicked through. The box replaces it with controls the agent cannot reach: an unprivileged identity with no sudo, a binary it cannot rewrite, no operator write credential, and the edge of a VM. Here is the stack:

On your host

torioThe host CLI creates and verifies the VM, installs the backend, and records non-secret instance and project configuration.

a session you open, over the VM's own SSH

Inside the Linux VM

The agentClaude Code or Codex, installed at a pinned version and run as its own unprivileged guest identity. It is a process you start inside a checkout, not a daemon: nothing is listening, on the guest or anywhere else.
Your Second BrainA private Markdown vault, versioned by its own Git repository, with a retrieval skill installed where the agent looks for one so any session can search it. Torio can import an existing vault into it; there is no export, because getting data back out is a copy you run yourself. The vault's format is a written standard, and it also ships as the Brain Kit plugin for Claude Code, usable against a directory of notes with no VM under it at all.
Your projectsRepository clones on the VM's own Linux filesystem — not on a host share reaching back into your home directory. The model sees the ones you registered, and no others.

The VM is a Lima instance. Torio creates it from a pinned template, installs pinned versions of what the backend needs, and can reconcile it later without touching your data — the same run twice changes nothing the second time.

What a session looks like

Run torio on a terminal. The hub verifies the box, shows the remaining setup steps, and runs the corresponding commands. The tutorial lists the same commands for scripts and manual use.

Open a project with torio project enter <id>, or from the hub. Work in the guest checkout, review git diff, then use torio project shell when you decide to push. The forwarded capability ends with the session.

Once you run more than one box, torio status is the command to remember. It polls every box Torio owns and reports one row each: whether it is running, what its agent has going, whether anything there is waiting on you, and when it last provably did work. It exits 0 whatever it finds, so your status bar or prompt can call it on a timer and only the box that wants you is loud.

Projects are a list you keep

The shared project registry stores ids, display names, and remotes. Workspace paths are derived from the backend and project id, never stored. Adding a project clones or adopts the exact remote; nothing is discovered from disk.

For a private SSH remote, Torio creates a guest-held deploy key and prints its public half. You add it to that repository with write access off. Torio cannot verify the forge setting, so adding it to an account would grant broader access.

What Torio will not do

Torio does not store credentials on the host. An operator shell may forward your SSH agent; pin one key to mediate signatures and optionally grant an agent session the same approval path. MCP OAuth is stored under the separate broker uid after an explicit login. Torio opens no public port, never pushes, merges, tags, or releases, and never deletes or re-images a VM. It is not a task queue, dispatcher, or worker platform.

The rest of these docs