This document describes how remote.futrx is put together: its runtime topology, the layers of the backend, the trust boundaries that matter for security, and where the load-bearing code lives. It is the map; the docs/ tree holds the per-subsystem deep dives, and the threat model analyzes the boundaries described here.
remote.futrx is a single-server, self-hosted workspace for Claude Code, Codex, MiniMax through the Codex harness, Kimi Code, and Antigravity. A user creates a project, the platform gives that project an isolated Linux container, and the user drives interactive or scheduled agent turns against the project's files from the browser—with chat, terminal, code editor, file manager, Git history, task schedules, and live app previews attached to the same project.
Everything runs on one host. There is no clustering, no external database, and no multi-node story (see Known limitations).
flowchart TB
User["Browser user"]
subgraph Host["Single host (Ubuntu/Debian, runs as root)"]
Caddy["Caddy — public HTTPS edge<br/>on-demand TLS, forward_auth, cookie stripping"]
Go["Go backend — 127.0.0.1:7682<br/>embedded Preact SPA + REST + WebSockets"]
Stores["Stores under DATA_DIR<br/>JSON metadata + JSONL chat logs<br/>derived SQLite chat index"]
LXD["LXD daemon"]
subgraph C1["Project container A (unprivileged LXD)"]
AgentA["Agent CLI (root, skip-permissions)"]
AppWeb["Optional installed application web service"]
AppA["Project dev servers"]
BrowA["Agent Browser — Chromium + noVNC :6080"]
end
subgraph C2["Project container B ..."]
end
end
User -->|HTTPS| Caddy
Caddy -->|"main host → loopback"| Go
Go -->|"authenticated label--project.host gateway"| AppWeb
Caddy -->|"<slug>--<port>.dev.host → :port"| AppA
Caddy -->|"<slug>--6080.dev.host → :6080"| BrowA
Go -->|reads/writes| Stores
Go -->|lxc CLI| LXD
LXD --> C1
LXD --> C2
Go -.->|"bind mounts /workspace, agent homes"| C1
Key facts about the topology:
- The Go backend is one process, bound to loopback (
HOST=127.0.0.1:7682,backend/internal/config/config.go). Caddy is the only thing listening on the public interface. - The backend runs as root (
infra/templates/remote.futrx.service.tmpl,User=root) because it drives thelxcCLI and chowns workspace files into the container idmap. This is a deliberate design choice with security consequences — see the threat model. - There is no external database service. Authoritative platform state is flat files under
DATA_DIR(/opt/remote.futrx/data): JSON for auth/users/projects/access/secrets and append-only JSONL for chat event logs. A disposable embedded SQLite database persists chat event offsets and transcript-turn ranges for bounded reads, validating them against JSONL file metadata and a prefix fingerprint before extending them. Concurrency is guarded by in-process mutexes only. - Each project is one unprivileged LXD container built from a shared base image (
futrx-remote-dev-base: Ubuntu 24.04 + Node 22 + pinned agent CLIs + Chromium). Durable state lives on the host and is bind-mounted in. Optional applications add their own software when installed.
Caddy (infra/templates/Caddyfile.tmpl) terminates HTTPS for the main host, project preview hosts, and installation app hosts. This routing table is the external attack surface:
| Host pattern | Routes to | Auth at the edge |
|---|---|---|
remote.example.com (main) |
Go backend on loopback | App session middleware; /internal/* blocked externally |
<slug>--<port>.dev.<host> |
Project dev server on <slug>.lxd:<port> |
forward_auth → /auth/verify (project membership enforced, or a valid public share link for that exact slug+port) |
<label>--<project-slug>.<host> |
Go application gateway → declared project app port | Session, registered account, project membership and running installation |
<slug>--6080.dev.<host> |
Agent Browser noVNC on :6080 |
forward_auth → /auth/verify (project membership, via the dev pattern) |
Two properties of this table are load-bearing and both are analyzed in the threat model:
- Wildcard subdomains use on-demand TLS, gated by the backend's
/internal/tls-askso only existing project previews and running web installations can mint certificates (project_handler.goHandleTLSAsk). - Caddy strips the platform cookies (
remote_session,remote_2fa_pending,remote_oauth_state,return_to,remote_share) viaheader_upbefore proxying preview requests into a container. The backend's authenticated application web route separately strips cookies before forwarding to an installed application's declared port.
The Go backend is strictly stratified. Requests flow down through the layers; lower layers never call up.
transport/ ── HTTP handlers, WebSocket sockets, auth middleware
│
service/ ── business logic: chat, prompt, project, user, auth, container/*, workspacefiles, ...
│
integration/ & stores/ ── the outside world: lxc CLI, git CLI, tmux, host fs, Google OAuth; file-backed stores
| Layer | Responsibility | Entry points |
|---|---|---|
| transport | Route parsing, session/membership gates, JSON encoding, WS upgrades | transport/transport.go, http/middleware/auth.go |
| service | All policy: what a request is allowed to do and what it means | service/services.go |
| integration | Typed wrappers over host tools (lxc, git, tmux, /proc, Google) |
integration/ |
| stores | File-backed persistence with in-process mutexes | stores/ |
Composition roots: backend/cmd/remote/main.go (server), backend/internal/service/services.go (services), backend/internal/config/containers.go (the container-capability stack).
Services.Mailer (service/email/mailer.go) is the one entry point for outbound email. A calling service composes a message with a fluent builder and never touches the stored SMTP configuration, MIME multipart, net/smtp, or HTML email markup:
err := deps.Services.Mailer.Mail().
ToUser(ownerEmail). // or .To("someone@example.com")
Subject("Your run finished").
Heading("Run finished").
Text("The agent finished the run you started.").
KeyValues([2]string{"Project", name}, [2]string{"Duration", d.String()}).
Button("Open the run", runURL). // http/https only; anything else fails the mail
Note("You are receiving this because you started the run.").
SendAsync(ctx) // or Send(ctx) when the outcome matters- Blocks, one shell.
Heading,Text,Button,List,KeyValues,Code,Divider,Notestack inside the single branded card. Each block renders both the HTML and its plain-text equivalent, so every message ships a matchingtext/plainalternative that nobody has to hand-write. - Errors are deferred to
Build, so the chain stays unbroken and the caller writes one error check.SendAsyncstill runs that validation and recipient resolution synchronously and returns the error immediately — only the actual SMTP round trip happens in the background, never a composition mistake. - One message per recipient, deduplicated — no recipient learns who else was mailed. Each recipient is its own SMTP session (there is no pooling), so a very large recipient list is not the intended use.
SendAsyncnever blocks a request: the background goroutine closes over the already-built messages, never the builder, and delivers on its own 30s budget with a bounded number of concurrent SMTP sessions (maxConcurrentSends), outliving the request context. Delivery is best-effort and in-memory — a send in flight when the process exits is lost.- An unconfigured server is a logged no-op, not an error — the same way push degrades without a VAPID key, and the log line masks the address (
j***@example.com). A feature must not fail because an administrator has not configured SMTP. Mail that must actually arrive — a 2FA code, an invitation — calls.Required()beforeSend/SendAsync, which turns that same case intoErrNotConfiguredinstead of a silent drop. The admin-facing test send inemail.ServiceusesRequired()for the same reason: an administrator asked directly and must be told.
email.Service still owns the configuration itself (normalise → verify against the live SMTP server → persist to DATA_DIR/smtp.json) and is handed only to the admin settings handler.
Three separate concerns, deliberately not conflated (deep dive):
- Platform identity. Exactly one local-admin account (email + password, argon2id, min 12 chars, in
local-admin.json); every other user signs in through Google OAuth only and must be invited first. There is no self-signup. The first claim is gated on a one-time token generated at startup and printed only to the server terminal (setup-token.jsonholds its SHA-256, never the token), so an unclaimed server cannot be taken over by whoever loads the page first; once an administrator exists, that administrator authorises any further claim instead. - Agent-provider credentials. Host-wide OAuth tokens for
Claude/Codex/Kimi, managed by an admin and shared by all projects and
users on the box. Claude and Codex can each retain multiple named
subscription credentials but expose one validated active host identity at
a time. The saved-account vault (
agent-accounts.json) and its activation rules belong toservice/agent/auth; provider adapters supply only credential placement, validation, identity, and isolated login. MiniMax instead readsMINIMAX_API_KEYfrom each project's secret store, while Antigravity authenticates throughagyinside one project and stores that state in its project-specific durable provider mount. - Per-project membership. A flat email access-list per project (
projectaccess/<id>.json). Any member — not only admins — can read/write that project's secrets and edit its member list.
Sessions are stateless HMAC-SHA256 tokens ({email, sub, iat, exp, sid}, 30-day expiry) signed by a random key at DATA_DIR/session.key (session_codec.go). The cookie is HttpOnly; Secure; SameSite=Lax and domain-scoped to the base host so it reaches preview subdomains for forward_auth. By default there is still no server-side session store: logout only clears the cookie, and per-request IsRegistered checks are the only way a session is invalidated early.
An account can opt in, from Settings → Security, to a small tracked-session model layered on top of the same stateless cookie, via three independent per-account toggles held in SessionRegistry (session_registry.go): single active session (a new login supersedes the account's previous session id, checked inside CurrentSession alongside the existing local-admin-vs-Google rule), sign-in history (a bounded, newest-first record of past logins), and recovery-code alert (settable only while TOTP 2FA is also enabled; flags a login that used a recovery code instead of the authenticator app, surfaced on /auth/me). TOTP 2FA itself is a fourth, independent toggle (twofactor.go) that adds a second factor to the login flow (/auth/2fa/verify) without requiring any of the other three. None of the four toggles affects an account that has not turned it on: CurrentSession's registry lookup, the history write, and the alert check are all short-circuited by the account's cached SecurityPreferences/2FA-enrollment state, so the stateless, zero-lookup path described above is exactly what unopted accounts still get.
Request gating (middleware/auth.go): the middleware covers /api/* and /ws* only. It requires a valid session for a registered user, then two setup preconditions: local admin claimed, and at least one module marked SatisfiesAccessGate ready. A no-auth gate module is ready immediately; managed code/device modules require an authenticated binding; external auth cannot be a gate because Remote has no authoritative status signal for it. The module-driven auth catalog and streams remain reachable while this gate is closed. Admin-only routes and project-membership routes re-check authorization per handler.
sequenceDiagram
actor User
participant SPA as Preact SPA
participant WS as /ws/chat/{id}
participant Prompt as prompt.Service
participant Runtime as module.Runtime
participant Provider as agent.Provider
participant Prep as execution.Preparer
participant Cmd as integration/agents/runtime
participant Projects as agent.ProjectResolver
participant LXD as LXD container
participant CLI as Agent CLI
User->>SPA: Type prompt, send
SPA->>WS: {type:"prompt", text}
WS->>Prompt: StartPrompt (single run per chat)
Prompt->>Runtime: validate scope + lookup provider
Prompt->>Provider: Run(provider-neutral request)
opt Project chat
Provider->>Prep: Prepare(project + selected features)
Prep->>Projects: resolve + start/reconcile
Projects->>LXD: enforce lifecycle
Prep->>LXD: provision CLI, credentials, and assets
Prep->>Projects: load project secrets
Prep-->>Provider: prepared container target
Provider->>Cmd: build common lxc exec envelope
end
Provider->>CLI: execute native host/container command
CLI-->>Provider: provider-native stream/protocol
Provider-->>Prompt: normalized agent events
Prompt-->>WS: normalized events (persisted to JSONL, broadcast)
WS-->>SPA: live text / reasoning / tool calls / usage
opt Successful project run with managed credentials
Provider->>LXD: best-effort credential sync to host
end
The run hub (service/runhub/hub.go)
enforces one run per chat, persists every event through the chat repository,
and replays history to reconnecting subscribers by sequence number. Provider
adapters (integration/agents/claude,
integration/agents/codex,
integration/agents/minimax,
integration/agents/kimi, and
integration/agents/antigravity) normalize each
provider's available output into a shared event stream. Antigravity print mode
provides plain streamed text rather than structured tool/usage events.
Agent composition uses the validated provider-owned factory contract in
service/agent/module. Each adapter
package exposes one NewFactory() from its local factory.go and is
compile-time checked against module.FactoryBuilder. The factory keeps public
descriptor metadata separate from its private provisioning profile and
project-preparation policy. AuthNone modules omit the binding; all other auth
modes require one. Project-capable modules must provide a profile; a host-only
module may provide one when it runs a locally installed CLI, or omit it for a
remote integration.
Catalog construction rejects duplicate or unsafe IDs, multiple defaults,
invalid auth/scope/feature combinations, and overlapping persistent-state
mounts before the server starts. Catalog.Build then returns one
module.Runtime that owns matching provider and authentication registries, so
consumers cannot combine state built from different catalogs. The provider
runtime contract itself stays narrow: identity, capability discovery, and
execution.
Provider-specific commands, protocols, parsers, credentials, capability
probes, and profiles live in the concrete
integration/agents adapters. Neutral
provider contracts remain in agent, and shared project
start/provision/secret orchestration lives in
service/agent/execution, while
integration/agents/runtime
assembles the common process and lxc exec command shapes used by those
adapters. Each provider factory declares its small preparation policy and
retains native CLI argument and transport ownership.
The explicit composition root in
config/agents.go only lists provider
NewFactory functions in deterministic order. There is no backend discovery or
package init registration. service.New passes application-facing
module.BuildDependencies—the narrow
ProjectResolver, full container ports,
and global credential-sync timeout—to Catalog.Build. For every project-scoped
module, module.Factory constructs execution.Preparer from a deep clone of
the validated profile and the provider's ProjectPreparationPolicy. It then
projects only ProjectPreparer, CredentialCollector, and the sync timeout
into the provider callback, alongside an independent validated profile clone.
Those factory dependencies do not expose project-service models or the full
container port set. Current adapters use the shared preparer; importing project
services directly or copying its CLI/workspace/browser/lifecycle workflow would
violate the integration contract.
When application authentication is enabled, service startup additionally
requires at least one managed or no-auth module that declares
SatisfiesAccessGate; this prevents a valid-looking catalog from leaving every
application route permanently behind an impossible onboarding gate.
The catalog also owns the provider default. At most one module may be marked default, and it must support host execution; Codex is the current built-in default. When no explicit provider is stored, chat creation, user settings, and skill lookup ask the catalog for the default compatible with the requested scope, falling back deterministically to the first compatible module.
A chat with no project ("loose chat") runs the CLI directly on the host instead of in a container. This path is convenient but removes the container boundary; its consequences are the subject of several threat-model entries.
| Data | Location | Format | Notes |
|---|---|---|---|
| Local admin | DATA_DIR/local-admin.json |
JSON | argon2id hash, mode 0600 |
| Users / roles | DATA_DIR/users.json |
JSON | admin/member rows |
| Project metadata | DATA_DIR/projects/<id>/meta.json |
JSON | slug is the container name |
| Project membership | DATA_DIR/projectaccess/<id>.json |
JSON | flat email list |
| Project secrets | DATA_DIR/projectsecrets/<id>.json |
JSON | plaintext, mode 0600, not encrypted at rest |
| Public preview links | DATA_DIR/projectshares/<id>.json |
JSON | SHA-256 token digests only, mode 0600 |
| Chat events | DATA_DIR/chats/<id>/events.jsonl |
JSONL | append-only, monotonic seq, no rotation |
| Agent quota snapshots | DATA_DIR/agent-quota.json |
JSON | latest provider-reported plan windows per provider account, mode 0600 |
| Chat event index | DATA_DIR/transcript-index.sqlite |
SQLite | disposable event-offset and transcript-turn index rebuilt from chat JSONL |
| Application agent receipts | DATA_DIR/application-turns/<instance-hash>/<request-hash>.json |
JSON | accepted input, turn identity and execution results |
| Application workflow state | each backend instance's DataDir |
application-owned | Scheduled Tasks stores definitions, deadlines and claims in tasks.json |
| Push subscriptions | DATA_DIR/push-subscriptions/sha256-<hash>.json |
JSON | one file per user, filename hashes the email |
| Web Push signing key | DATA_DIR/webpush-vapid.json |
JSON | VAPID P-256 pair, mode 0600; rotating it invalidates every browser subscription |
| Session key | DATA_DIR/session.key |
32 random bytes | mode 0600 |
| Google OAuth secret | DATA_DIR/oauth.json |
JSON | plaintext, mode 0600 |
| SMTP credentials | DATA_DIR/smtp.json |
JSON | Gmail address + app password, plaintext, mode 0600 |
| Provider tokens | /root/.claude*, /root/.codex, /root/.kimi-code |
provider files | copied into every container |
| MiniMax project state | /var/lib/remote/projects/<slug>/agent-home/minimax |
Codex-harness files | bind-mounted to /root/.minimax; its API key remains in the project secret store |
| Antigravity project auth/session | /var/lib/remote/projects/<slug>/agent-home/antigravity |
provider files | bind-mounted to /root/.gemini/antigravity-cli; survives container replacement |
| Workspace files | /var/lib/remote/projects/<slug>/workspace |
on-disk tree | bind-mounted to /workspace |
| Agent homes | /var/lib/remote/projects/<slug>/agent-home/* |
on-disk tree | bind-mounted to /root/.claude etc. |
JSON and metadata writes use temp-file + rename. Chat events are different: they append directly to JSONL with O_APPEND. The SQLite chat index is derived state, transactionally refreshed from those logs, and is not a source of truth. Most authoritative stores do not add fsync, file locking, or a transaction spanning multiple stores. Application agent receipts and Scheduled Tasks snapshots fsync both file and directory. The design assumes exactly one backend process touching DATA_DIR.
Containers are cattle; durable state lives on the host and is bind-mounted in (deep dive, lifecycle/service.go):
- Six bind mounts per project:
workspace→/workspace, plus the provider-declared persistent directories for Claude, Codex, MiniMax, Kimi, and Antigravity. Antigravity mounts only/root/.gemini/antigravity-cli, not the whole.geminitree. Host dirs are chowned to uid/gid1000000(the unprivileged-root idmap) viaos.OpenRoot+Lchownto defeat symlink-swap races. - A managed LXD profile (
futrx-workspace,resources/manager.go) targets 4 GiB memory, 6 CPUs, 2000 processes and setssecurity.nesting=truefor nested-container workloads. Chromium currently launches with--no-sandbox, so that setting is not a Chromium sandbox guarantee. Default/profile resource convergence is best-effort because errors from the defaultresources.Ensurepath are discarded; explicit per-project overrides fail launch when they cannot be applied. There is no default disk quota. - Networking: containers share LXD's default bridge; Caddy reaches them by
<slug>.lxd:<port>DNS. The bridge has no inter-container ACLs by default. - Everything else crosses via
lxc file push/pullandlxc exec: credentials, project secrets (asenvironment.*config and--envargs), agent instructions, provider runtime assets, and skill links.
The rootfs is disposable — upgrade-workspaces replaces containers wholesale onto a new base image, so anything installed outside /workspace and the agent homes is lost on upgrade.
Scheduled Tasks is an installable project application. Its backend owns the clock, cron calculation, task definitions, claims, completion rules and next occurrences. Its CLI, skill and UI ship in the package. New tasks are active; the retired core scheduler's data is not automatically imported.
Core provides a generic installation-scoped Runtime.AgentTurns capability for
starting and reading ordinary agent turns, durable execution receipts, scoped
application tool calls and opt-in background backend recovery. The applications
service owns policy; the SDK and application process host provide the contract
and RPC transport; provider integration stays in internal/integration/agents.
Other applications use these same capabilities without scheduler dependencies.
See Application agent runtime for execution authority and recovery, and Scheduled tasks for the application-owned workflow.
Project containers expose these capabilities (deep dive):
- App previews: the backend runs
ssinside the container to discover listening ports (listeners/scanner.go, loopback binds excluded), and each becomes a<slug>--<port>.dev.<host>URL. No per-app proxy config is written — DNS + Caddy regex do the routing. - Installed application web services: an application can declare a project port and a required
web.subdomainlabel. The backend checks membership and installation status on every<label>--<project-slug>.<host>request./apps/<slug>/<application-id>/only redirects to that isolated origin. No editor is installed by core. - Agent Browser: one shared headed Chromium per project, driven by the user via noVNC (
:6080) and by the agent via MCP-over-CDP (127.0.0.1:9222) — the same browser session, so the agent inherits whatever sites the user logged into. The human UI can start and view it directly; selecting thebrowserskill enables agent MCP access for Claude, Codex, or MiniMax.
A Preact (not React) SPA built with Vite + Tailwind, whose production build is embedded into the Go binary via go:embed and served same-origin (deep dive). It is an installable PWA: frontend/public/ supplies the manifest, icons, and a service worker for Web Push plus network-first navigation. The worker deliberately does not cache the app shell or API data; it caches only the self-contained /offline.html fallback and serves it when navigation cannot reach the network. Cache cleanup is restricted to Remote-owned offline-cache names.
Notifications. The backend raises a Web Push notification when an agent calls AskUserQuestion, when a turn completes or fails, and when a scheduled run finishes. The trigger hangs off the chat repository's append path (push_notifier.go), so every producer — interactive prompts, scheduled runs, crash recovery — is covered by construction. The audience mirrors chat visibility: project members plus admins, or every registered user for a loose chat. VAPID signing and RFC 8291 payload encryption are implemented against the standard library only (integration/webpush), so push services relay ciphertext they cannot read and the dependency list is unchanged. It is strictly layered (config → models → transport → api → state → app → ui), uses no external state store and no URL router, and talks to the backend over REST (fetch, cookie session) plus WebSockets for live data. All auth is the same-origin cookie — no token ever touches JavaScript, and there are no CSRF tokens (protection rests on SameSite=Lax and the same-origin edge). The markdown renderer emits vnodes only, with an href allowlist and no innerHTML, keeping the XSS surface narrow — the one place the SPA does assign markup is the catalog extension host below, which renders assets compiled into the binary rather than anything a request supplied.
Catalog UI extensions. An installable application may ship a ui/
directory (applications/README.md), and
the SPA loads it for the apps a user has installed — globally, or in a
project they belong to, and only while the instance is running
(GET /api/applications/ui; being in the catalog grants nothing). The install
scope travels with each entry and becomes the render scope: a globally
installed extension draws everywhere, a project-installed one only while the
user is actually working inside that project — leaving it puts the extension
away entirely — which the registry enforces per contribution rather than
trusting the extension. Stylesheets
are injected, scripts/main.js is dynamically imported, and it registers
contributions into a closed set of named slots (frontend/src/app/extensions/):
the chat header rail, the composer deck, project rows, the sidebar header and
its search field, and the applications surfaces. This is what lets a backend add
interface — an icon that opens a workspace in another editor, a panel, a popup,
a pane docked beside the chat —
alongside whatever its install.sh provisions in a container. Each slot carries
its own icon sizing, so a contributed button matches its neighbours without the
extension knowing the app's chrome densities.
Contributions render into plain DOM nodes rather than the component tree, so
extension code stays framework-free, and a throwing entry module, predicate, or
handler is caught per contribution.
An application also declares a type: a service application runs software on a port and
gets a container (a dedicated LXD one at global scope), while ui and
backend applications install nothing in any container — their whole payload is the
extension or the backend, so installing one allocates no container, port, or
proxy device. That keeps "add a button to the UI" from provisioning a Linux
container to do it, and both install on a host with no container runtime at
all.
Catalog application backends. The other half of "everything is a backend": an
application may also ship a backend/ directory of Go source
(docs/dev/installable-applications/15-application-backends.md).
The server compiles it and runs it as a child process over
hashicorp/go-plugin, one process per installed instance, and forwards HTTP
calls to it at /api/applications/<instance>/backend/<path> — which the
application's own ui/ reaches through remote.backend.call(...). So an application can
add a server-side feature rather than only a button that calls an endpoint
someone else had to write. The contract a backend implements is
pkg/applications, a dependency-free package of wire
types; the transport that carries it is pkg/applications/rpc, deliberately
go-plugin's net/rpc mode rather than gRPC, since backends are Go programs
compiled from a catalog embedded in this same binary and a language-neutral
protocol would buy nothing but protobuf codegen.
The catalog ships source, not binaries, because it is embedded in a server
that runs on whatever architecture it runs on, and because source is reviewable
as a diff. internal/integration/applications
materializes an application's backend/ beside a copy of the SDK into a generated
module whose dependency versions are read from the running binary's own build
info — so go build resolves entirely from the module cache the server's build
already populated, and the normal path needs no network. Binaries are cached by
a fingerprint of source, SDK, module files, and Go version, so a cold build
happens once per edit and every later start is a stat and a handshake. Backends
recover lazily on the next call by default. backend.background opts running
installations into startup and periodic recovery; stopped installations stay
stopped. The per-instance DataDir retains application state. Generic agent
execution receipts also survive separately under DATA_DIR/application-turns.
The trust boundary here is the build, not the request — for both halves,
and it has to carry more weight for the backend one. ui/ assets are embedded
by //go:embed next to the SPA and served from
/api/applications/catalog/<application>/ui/<path> to signed-in users only, so
extension code carries exactly the privileges of first-party frontend code and
is reviewed as such. backend/ source is embedded the same way and then runs
as a child of the server process, with the server's privileges and the
install's secrets, so it is reviewed as backend code. There is no sandbox for
either and none is implied; the server-side guarantees are narrower and
specific — the registry resolves asset paths inside one application's ui/ and
nowhere else, responses are typed from the file extension with nosniff, and
on the backend path the caller identity is stamped from the session while the
caller's own Cookie and Authorization headers are withheld, so a backend can
authorize a user without being able to act as them. Process isolation buys
robustness rather than containment: a panicking or hanging backend costs one
call, not the server.
Agent authentication UI. The frontend loads ordered module metadata and a
normalized auth snapshot from GET /api/agent-auth, then subscribes to
/ws/agent-auth/<provider> for each managed flow. The same descriptor fields
drive onboarding eligibility, Settings cards, provider labels/instructions,
and code-versus-device controls. External and no-auth modules render without
inventing managed login actions. Legacy provider-specific status endpoints and
WebSockets remain available for compatibility, but the current UI does not
depend on their provider-specific payloads.
Deployment is a single-box, root-driven, idempotent-converge model (deep dive):
infra/install.shis both bootstrap and deployer. It clones/selects/opt/remote.futrx, re-executes the chosen checkout, then walksinfra/steps/00..07(checkout guard, host deps, host agents/app build, Caddy, systemd service, base image, SSH hardening, network-heal timer). It is re-runnable without mixing manifests from the old and selected commits.- Host agent CLI installation is catalog-driven. After selecting the target
checkout, the application step runs
cmd/install-host-agents, which converges every host-scoped module with a local profile using that profile's binary, provider-declared version arguments, exact semver pin, npm package or install script, timeout, and verification policy. Every installer mode targets the application-owneddata/host-clisprefix; the installer, systemd service, and login-shell profile all put itsbindirectory first and verify that ordinary command resolution selects the same absolute executable that was installed. This prevents a stale host-global binary from shadowing a newly installed pin. Host-only remote integrations may omit a profile and install nothing. The base image and runtime repair consume the same profiles for project-scoped modules. infra/update.shfetches and hard-resets to the requested tag/ref (defaultorigin/main), rebuilds, and recycles containers onto a fresh base image. Busy-workspace detection is intended to skip active runs but is not currently reliable; use a maintenance window or--skip-workspaceswhen interruption is unacceptable.- CI publishes releases; it does not deploy production.
.github/workflows/release-on-tag.ymlcreates a GitHub Release for a semantic-version tag after classifying it. Production changes are applied separately by an operator through Remote's updater orinfra/update.sh. - Version pinning: core pins for agent CLIs, the host toolchain, and Playwright/Chrome-for-Testing live in one manifest (
versions.env, symlinked atinfra/versions.env), embedded by the backend and sourced by the infra scripts. Applications pin their own dependencies. The Playwright browser archives additionally have sha256 pins backing a vendored fallback (vendors/) for servers geo-blocked by Google's CDN; the remaining upstream fetches (NodeSource, the Go tarball, the Ubuntu base image) are version-pinned but not checksum- or signature-verified.
The security consequences of applying unsigned update refs as root and of unverified upstream fetches are covered in the threat model.
These are the boundaries the threat model reasons about:
- Internet → Caddy → backend. External users hit only Caddy; the backend trusts Caddy's
X-Forwarded-*headers because only loopback reaches it. - Registered user → other users' projects. Enforced per-resource in handlers and at
forward_auth; project previews and application web routes check membership. - Container → host, and container → sibling container. Unprivileged LXC namespaces plus resource caps are the boundary; the shared bridge and in-container
auth: noneservices are the soft spots. - Agent → everything it can reach. The agent runs as root inside its container (or on the host for loose chats) with safety rails off, so any content it ingests (web pages, files, attachments) is a potential injection vector.
- Host → upstreams. The root-run installer, updater, and base-image build pull code and packages from GitHub and external registries; release CI is a separate publication path and does not deploy the host.
docs/01-overview/— system overview and the code mapdocs/02-workspaces/— auth, projects/containers, chat/agents, workspace toolsdocs/dev/agents/— agent module contracts and the complete extension guidedocs/dev/installable-applications/— the installable-application format, extension slots, and application backendsdocs/03-platform/— previews & browser, data & frontend state, API & realtimedocs/04-operations/— deployment and operations- Threat model · Known limitations