> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/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
  service -- "uploads (HTTPS)" --> cloud[("rakumux.com<br/>Postgres")]
  service -- "polls for replies (HTTPS)" --> cloud
  web["Web app<br/>(any browser)"] -- HTTPS --> cloud
```

Your machine always calls out to rakumux.com. Nothing calls in, so there's no VPN or open port.

## 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

With the Agent feed on, 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`).

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 web app

rakumux.com reads what your machines uploaded, signed in with your account: its Sessions view
(grouped by status, folder or app) and its Feed. 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://rakumux.com/docs/phone/remote-access.md)).


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