System overview#
What the application is#
remote.futrx is a self-hosted browser workspace for Claude Code, Codex, and Kimi Code. Users create isolated projects, run agent chats against those projects, and inspect the result through chat, files, Git, a terminal, an IDE, or a live app preview.
Runtime architecture#
flowchart LR
User["Browser user"] -->|"HTTPS"| Caddy["Caddy"]
Caddy -->|"Main UI, API, WebSockets"| Go["Go backend"]
Go --> SPA["Embedded Preact SPA"]
Go --> Stores["JSON and JSONL stores"]
Go --> Host["Host integrations"]
Host --> LXD["LXD"]
Host --> Git["Git CLI"]
Host --> Tmux["tmux and PTY"]
Host --> Info["Host resource collector"]
LXD --> P1["Project container A"]
LXD --> P2["Project container B"]
P1 --> Agent["Agent CLI"]
P1 --> IDE["code-server"]
P1 --> Apps["Project web apps"]
P1 --> Chromium["Agent Browser"]
Caddy -->|"*.code host"| IDE
Caddy -->|"slug--port.dev host"| Apps
Caddy -->|"slug--6080.dev host"| Chromium
Application layers#
| Layer | Responsibility |
|---|---|
| Frontend | Authentication gates, workspace navigation, chat rendering, drawers, settings, and API clients |
| HTTP and WebSocket transport | Routes, JSON responses, upgrades, session checks, and project membership checks |
| Services | Chat, prompt, project, user, settings, skills, Git, files, browser, and container policy |
| Integrations | LXD, Git, tmux, host filesystem, Google OAuth, host metrics, and container commands |
| Stores | File-backed auth, users, settings, chats, projects, access lists, and secrets |
| Infrastructure | Installation, systemd, Caddy, LXD image creation, updates, and recovery timers |
Main user surfaces#
flowchart TD
Gate["Authentication and onboarding gate"] --> Shell["Workspace shell"]
Shell --> Sidebar["Project and chat sidebar"]
Shell --> Chat["Chat view"]
Shell --> Projects["Project workspace controls"]
Shell --> Settings["Settings"]
Chat --> Composer["Provider, model, mode, skills, attachments"]
Chat --> Messages["Text, reasoning, tools, usage"]
Chat --> Drawers["History, files, browser"]
Chat --> Terminal["Terminal overlay"]
Projects --> Lifecycle["Start, stop, restart, delete"]
Projects --> Inspect["Resources, network, agent status"]
Projects --> Manage["Limits, secrets, sharing"]
Settings --> Agents["Agent sign-in"]
Settings --> Appearance["Theme"]
Settings --> Users["Google OAuth and users"]
Settings --> Server["Host resource information"]
End-to-end work flow#
sequenceDiagram
actor User
participant UI as Browser UI
participant API as Go backend
participant Project as Project service
participant LXD as LXD container
participant Agent as Selected agent CLI
User->>UI: Create a project
UI->>API: POST /api/projects
API->>Project: Create metadata and membership
Project->>LXD: Launch from the base image
LXD-->>Project: Running workspace
Project-->>UI: Project upsert over workspace WebSocket
User->>UI: Create chat and send prompt
UI->>API: Open /ws/chat/{id}
UI->>API: prompt message
API->>Project: Ensure project is running
API->>Agent: Run or resume CLI in /workspace
Agent-->>API: Normalized text, reasoning, tool, session, usage events
API-->>UI: Persisted event stream
UI-->>User: Render live progress and result
Workspace navigation#
The sidebar groups chats under projects and keeps loose chats in a separate section. It supports project/chat search, project reordering, unread and running indicators, project start/stop actions, new project or chat creation, chat fork/delete, and read/unread toggling. Selecting a chat closes the mobile sidebar and opens its active ChatContainer.
The main shell switches between three views without browser routing:
| View | Main features |
|---|---|
| Chat | Streaming thread, composer, terminal, files, Git history, and browsers |
| Project workspaces | Lifecycle, diagnostics, limits, secrets, and sharing |
| Settings | Provider sign-in, system/dark/light theme, Google users, and server metrics |
Important boundaries#
- The host owns authentication, metadata, HTTPS, access decisions, and container orchestration.
- Each project owns its
/workspacefiles and processes. - Agent credentials are host-managed and synchronized into project containers.
- The workspace WebSocket carries project/chat list updates; each chat has its own event stream.
- Caddy authenticates IDE and preview requests before proxying them into containers.
Code map#
- Frontend entry:
frontend/src/app/App.tsx - Backend composition root:
backend/cmd/remote/main.go - Service composition:
backend/internal/service/services.go - Container composition:
backend/internal/config/containers.go - Reverse proxy template:
infra/templates/Caddyfile.tmpl