> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rakumux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the TUI, the background server, the account service and rakumux.com fit together.

```mermaid theme={null}
flowchart LR
  subgraph machine["Your machine"]
    tui["rakumux<br/>TUI and CLI"] -- Unix socket --> ptyd["rakumux-ptyd<br/>server"]
    ptyd -- PTYs --> agents["Agents and shells"]
    service["Status service"] -- Unix socket --> ptyd
  end
  subgraph cloud["API"]
    api["rakumux.com API"]
  end
  service -- "uploads (HTTPS)" --> api
  service -- "polls / pulls for replies (HTTPS)" --> api
  web["Web app<br/>(any browser)"] -- HTTPS --> api
```

## Your machine pulls

Your machine only ever makes outgoing HTTPS requests to the rakumux.com API. It sends what's new,
and it asks for what's waiting for it: replies you wrote, sessions you asked for. Nothing on the
internet connects in to your machine. That means:

* **No networking to set up.** No Tailscale, WireGuard or other VPN, no port forwarding, no open
  ports, no public address or dynamic DNS. If your machine can open a website, it works: at home,
  behind a company firewall, on hotel Wi-Fi, or on a Sprite.
* **Nothing to attack from outside.** Your machine listens for nothing from the internet, and
  rakumux.com has no way in. It only holds replies until your machine asks for them, and your
  machine decides what to type in and when. (Your Sprite is the exception: your computer reaches
  it at its own Sprite URL, with a token, and rakumux.com only calls that URL to wake it.)
* **A sleeping machine misses nothing.** A reply waits on rakumux.com until your machine is back
  and pulls it.
* **Still quick.** Your machine also keeps an outgoing realtime connection open. When a reply
  arrives, rakumux.com pokes it to pull at once. The poke carries no content. While you're active,
  it asks every second.

## On your machine

* **`rakumux-ptyd`** owns every session: one per user, it runs each session's terminal, keeps it
  running with no window open, tracks what each agent is doing and reads the agents' conversation
  logs. Everything talks to it over a private Unix socket.
* **`rakumux`**, the TUI and CLI, is a client of the server. Any number can connect at once.
* **The status service** (`rakumux status-service`) starts when you sign in. It's another client
  of the server, holds your sign-in, and is the only part that talks to rakumux.com. The TUI's Feed
  tab reads through it.

## Up to rakumux.com

Signed in, the status service sends, with your account's token:

* **Each finished turn**, the agent's reply, as it finishes (`/api/v1/feed/entries`).
* **The chat**: prompts, replies, reasoning, tool calls and output, with secrets masked, as it
  grows: every 5 seconds, or every second while that machine checks for replies every second
  (below) (`/api/v1/feed/messages`).
* **The session list**: names, folders, branches, agents and status, when it changes and every
  minute (`/api/v1/feed/sessions`).
* **What the machine uses**, for rtop on the web: CPU, memory and network for the machine,
  Rakumux's own processes and each listed session, every few seconds, only while someone has rtop
  open there (`/api/v1/feed/resources`). No process names or command lines.

It's all stored in Postgres under your account. Private sessions are never sent.

## Back down to your machine

1. You write a reply on the web (or in another machine's TUI). It's stored as **pending** for the
   session's machine.
2. That machine's status service polls `GET /api/v1/feed/replies`. Each answer says when to ask
   again (`poll_ms`): every second while a reply waits for it, while you have the website open, or
   for 30 seconds after a reply was written or typed in anywhere; then less often as replies go
   quiet (2, 4, 8 seconds), down to every 15 seconds after 4 minutes.
3. Once the session's agent is waiting for input, the status service types the reply in through
   the server (a paste, then Enter). It never types into a shell, a private session or a question the
   agent is asking, and waits while someone is typing in that session.
4. It reports the reply **sent** (or why not), and uploads the agent's next turn as its answer.

The same read brings the new sessions you asked that machine for on the web (a folder's name and an
agent, never a path or a command). The status service starts each through the server in that folder,
reports it started (or why not), and your first prompt follows as a reply.

## The web app

rakumux.com reads what your machines uploaded, signed in with your account: its Sessions view
(grouped by status, folder or app), and beside it a drawer with its Feed and rtop. The web never
connects to your machine.

The phone app can also reach a machine directly over Tailscale, through its local HTTP API (see
[Phone access](https://docs.rakumux.com/phone/remote-access.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.