Torio

Thin control plane · macOS and Linux

Your AI second brain, on a Linux VM you actually control.

Torio creates the Linux VM, runs a Hermes backend on the VM's own loopback, tells you in one command whether the whole stack is healthy, and gives the model access to exactly the repositories you listed. You open the connection, you hold the credentials, you decide what gets committed.

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. Six moving parts, split across the two machines:

On your host

torioThe Torio CLI, and the only part of this that we wrote. It creates the VM, installs the backend as a service, proves the service is genuinely answering, and registers your projects. It has no daemon and holds no state of its own.
Hermes DesktopThe chat app you already use, pointed at a URL instead of a local backend. This is where you actually talk to the second brain and to the code.
Your ssh -LThe one and only route from the host to the backend. You open it in a terminal you can see, and close it when you are done.

localhost:19119 → the VM's 127.0.0.1:9119

Inside the Linux VM

Hermes backendA hermes serve process, run as a user systemd service so it survives logout and restarts on its own. It binds 127.0.0.1 of the guest: nothing on your network, and nothing on your host, can reach it except through your tunnel.
Your Second BrainA private Markdown vault, versioned by its own Git repository and registered with Hermes 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.
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

First run is a short, ordered sequence. After that, torio serve status is the one to remember: it reports the systemd unit, the loopback endpoint and the Hermes version, so a backend that stopped answering names itself instead of leaving you to guess.

first run
$ torio vm init          # create the VM from a pinned template
$ torio vm bootstrap     # install and verify what the backend needs
$ torio serve install
$ torio serve start      # backend up on the VM's own loopback
$ torio serve status     # and prove it answers
Backend ready on http://127.0.0.1:9119/api/status
  systemd:  active (active=true, enabled=true)
  endpoint: 200 (ready=true)
$ torio brain init       # your private, searchable Markdown vault
$ torio project add my-service https://github.com/you/my-service --use
— then, in a second terminal you leave open —
$ ssh -L 19119:127.0.0.1:9119 …  # your tunnel; now Desktop can connect

From there you point Hermes Desktop at http://127.0.0.1:19119, paste the session token the backend requires, and work. On the code side the loop is yours end to end: edit or ask for edits, run a check that reads rather than writes, read git diff — and when you decide something should leave the VM, torio project shell gives you a session that can push and takes the capability back when you exit.

Projects are a list you keep

The model can only see repositories you have registered. That list is a plain file you own: each entry names a repository and where its clone lives on the guest, and it holds no credentials of any kind. Adding a project clones it into the VM and registers it with Hermes; nothing is discovered, scanned, or picked up automatically because it happened to be on disk.

Read access to a private repository is your job, set up by you on the guest. Torio never stores a token, never prompts for one, and never passes one to the model — a workspace it prepared has no push credentials in it at all.

What Torio will not do

The narrowness is the point. Torio never holds or prompts for a credential — the one it forwards is your SSH agent, into a session you opened, for as long as you keep it open. It never opens a tunnel or exposes a port beyond the guest's loopback. It never commits, pushes, merges, or tags — those are yours, always. It never deletes or re-images a VM, and it takes no data back out of one. And it is not an agent platform: no task queue, no dispatcher, no fleet of autonomous workers running while you sleep.

The rest of these docs