Skip to main content

​
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).