Architecture

​

Components

The control plane is a TanStack Start application on Bun. It owns identity, encrypted model configuration, durable conversation state, model streaming, artifact authorization and metadata, and Kubernetes reconciliation. PostgreSQL is authoritative for users, projects, memberships, chats, participants, messages, artifact metadata, workspace intent, and audit history. Artifact bytes live separately on the retained control-plane artifact PVC. 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 home PVC is private to that user. It is not shared artifact storage. Project and standalone-chat artifacts follow a separate path: agent code uses the Unix-friendly r5dchat artifacts CLI, which calls the internal control-plane artifact API with workspace identity and a conversation-derived scope. The control plane re-checks project membership or chat participation and then reads or writes the artifact service. This contract keeps storage replaceable without changing agent behavior. 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.

​

Trust boundaries

• Browser sessions may access only projects, chats, and artifact namespaces for which the authenticated user has membership or participation.
• A per-workspace random bearer identity maps to exactly one user. It is mounted from a Secret and never displayed to users or models.
• Workspace artifact requests require both that identity and an x-artifact-scope derived from the current conversation. Supplying a project, chat, or namespace identifier never grants access by itself.
• ARTIFACT_SCOPE is injected into each spawned shell process, not set globally on the workspace pod, so concurrent chats cannot reuse ambient scope.
• Artifact paths are normalized, user-visible paths are distinct from opaque storage keys, and bytes never mount into the workspace home.
• 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.

​

Lifecycle

Chat, private-file, and process activity starts a workspace and updates its lease and activity record. Artifact browsing and upload operate in the control plane and do not require artifact storage to mount into a workspace. An idle reconciler scales the Deployment to zero only after all active leases finish. The Service, Secret, and private home PVC remain. Explicit purge is a separate, deliberately audited administrator action, because PVC deletion is destructive and irreversible.

​

Conversation-owned agents

A chat is the durable agent identity: transcript, model choice, input inbox and execution state. running means its server-owned model/tool loop is active. Submitting an ordinary message does not create an automation job. Inputs arriving while the agent is active are saved for its next turn or delivered as steering at a safe boundary. Separate chats execute independently with no numeric concurrency cap; a fencing lease prevents two servers from owning the same agent state. The server calls model providers and coordinates tools; workspace tools execute remotely in the user’s pod. Internal generation IDs and model/tool receipts support stream replay, cancellation and recovery, not a separately managed Run product entity. Browser disconnect does not stop the agent. Unknown effects after a crash require owner review rather than automatic redispatch. Automation schedules and command jobs retain their own occurrence history and use the same model/tool engine. Parallel tools remain unrestricted except write/edit calls to the same normalized lexical path for an owner, which are ordered within one server process. Shell writes, path aliases and other server processes are outside that coordination.

​

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, the artifact PVC, and SETTINGS_ENCRYPTION_KEY as one recovery unit. Snapshot user home PVCs separately 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, shared artifact storage, and dynamic user homes use separate retained PVCs. The artifact claim and user claims 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.