Skip to main content

​
Components

The control plane is a TanStack Start application on Bun. It owns identity, encrypted model configuration, durable conversation state, model streaming, and Kubernetes reconciliation. PostgreSQL is authoritative for users, chats, messages, workspace intent, and audit history. Each user maps to one deterministic Service, Recreate Deployment, identity Secret, and retained ReadWriteOnce PVC. The Deployment scales between zero and one, and the complete PVC mounts at /home/r5d with no subPath. Inside the pod, r5dchat daemon exposes a private authenticated HTTP protocol for filesystem, search, and process operations. The browser only ever calls the control plane.

​
The workspace image

A general-purpose Debian environment containing Bun, Node.js and npm, Python with pip and venv, native build tools, Git and GitHub tooling, common database clients, and plotting and data libraries. Media tooling includes FFmpeg and ffprobe, ImageMagick, libvips, ExifTool, image optimizers, Tesseract, and broad fonts. Document tooling includes LibreOffice headless, Recoll and Xapian, Pandoc, Poppler, qpdf, Ghostscript, and Python office libraries. Recoll performs incremental ranked discovery across document contents; AnyDoc converts a selected Office or PDF document to Markdown on demand.

Image contents in detail

The full toolchain and how to build your own variant.

​
Trust boundaries

  • Browser sessions may access only records owned by the authenticated user.
  • A per-workspace random bearer identity maps to exactly one user. It is mounted from a Secret and never displayed to users or models.
  • Tenant containers receive no Kubernetes service-account token, host path, runtime socket, or privileged capability.
  • UI file APIs are confined to canonical paths below the home directory. Agent tools intentionally operate anywhere inside the container.
  • Provider and web-research secrets are AES-256-GCM encrypted with the installation key and stay in the control plane.
  • Public provider URLs reject credential-bearing URLs, unsafe redirects, link-local, metadata, and private destinations, and non-HTTPS by default.
Root in an unprivileged container is not a complete sandbox for hostile code. Production operators serving untrusted tenants should add Kata or gVisor, Pod Security admission, NetworkPolicy, quotas, isolated node pools, image policy, and monitoring.

Full security model

Hardening checklist and multi-tenancy guidance.

​
Lifecycle

Chat, file, upload, preview, and process activity starts a workspace and updates its lease and activity record. An idle reconciler scales the Deployment to zero only after all active leases finish. The Service, Secret, and PVC remain. Explicit purge is a separate, deliberately audited administrator action, because PVC deletion is destructive and irreversible.

Lifecycle operations

Inspecting, resizing, and removing workspaces.

​
Conversations and fresh context

A conversation owns one ordered message stream. Starting fresh context appends a flagged system prompt to that same stream: provider context begins at the latest flag while the durable transcript remains complete. The flagged prompt tells the agent to begin with r5dchat conversation overview <conversation-id>, inspect selected details with r5dchat conversation turn <conversation-id> <turn-id>, or fall back to r5dchat conversation read <conversation-id> for the full transcript. The CLI uses workspace identity, and the server re-checks user ownership before returning Markdown or JSON.

​
Backup and recovery

Back up PostgreSQL and SETTINGS_ENCRYPTION_KEY as one recovery unit. Snapshot user PVCs according to storage-provider policy. Retain BETTER_AUTH_SECRET to preserve active sessions. Losing the settings key makes encrypted provider and OIDC credentials unreadable. Replacing it is not a rotation procedure, because existing data is not re-encrypted.

​
Uninstall and upgrade

The bundled database uses a retained StatefulSet PVC. Dynamic user PVCs carry keep semantics and are not owned by transient Deployments. Back up before upgrades, run migrations once, and test restore procedures. Uninstalling compute does not mean deleting tenant data.