Plan Remote Workspace Gateway with local runner architecture

[manishiitg]

Summary

Track future implementation of Remote Workspace Gateway + Local Runner mode.

The target model is: the server owns the single workspace-docs copy and secure workspace/tool access, while the local desktop app remains the agent runner that hosts agent_go, coding CLIs, mcpbridge, schedules, Pulse, and auto-improve.

This is a future backlog item, not an implementation task for the current release.

Target architecture

• Server: SSO/device grants, one live workspace-docs, secure file/search/db/shell/browser tool APIs, folder guards, leases, audit logs, backups/snapshots.
• Local runner: Runloop UI/control plane, local agent_go, Claude Code/Codex/Cursor, local mcpbridge, plan tools, get_reference_doc, schedules, Pulse, auto-improve.
• Flow: coding CLI -> local mcpbridge -> local agent_go tool handler -> WorkspaceClient / WORKSPACE_API_URL -> HTTPS Remote Workspace Gateway -> server workspace API / workspace-docs.

Key requirements

• Do not create a duplicate server-hosted Runloop control plane.
• Do not keep local synced working copies of workspace-docs.
• Use token-based SSO/device auth; do not trust caller-supplied user IDs.
• Keep get_reference_doc local because it is embedded product guidance, not workspace data.
• Plan tools stay local but mutate remote planning/plan.json through WorkspaceClient and server-side leases.
• File, search, db, shell, and browser workspace tools run against the remote gateway in remote mode.
• Server-side workflow write leases prevent concurrent conflicting edits.
• Server-side schedule claim leases prevent two local runners from executing the same due schedule.
• If no local runner is online, schedules wait. A dedicated always-on runner can be a later optional mode.

Implementation phases

1. Add remote workspace profile/mode boundary.
2. Add SSO + Connect Desktop/device token flow.
3. Harden gateway auth, folder guards, request limits, logging, and audit trails.
4. Route workspace tools through remote WORKSPACE_API_URL without falling back to localhost in remote mode.
5. Add workflow write leases and scheduled-job claim leases.
6. Audit CLI scratch directory/context routing so coding CLIs never accidentally mutate the wrong local workspace.
7. Add migration/backup path and make the server copy the source of truth.

Manual validation checklist

• SSO import/revoke works; spoofed X-User-ID is denied.
• User A cannot read or write User B/private workflow data.
• Remote profile never silently falls back to local workspace-api.
• get_reference_doc still works locally.
• Plan edits affect only remote planning/plan.json; raw writes to protected planning files are blocked.
• Two runners cannot double-run the same due schedule.
• Two users cannot concurrently edit the same shared workflow without a lease conflict.
• Laptop-off schedules wait and later execute once a runner is online.
• Shell path traversal, symlinks, and absolute host paths are blocked.
• Secrets and tokens are redacted from logs and audit trails.
• Local CDP/browser automation and server-side browser sessions are clearly separated.
• Migration retires old local copies instead of leaving two sources of truth.

Related docs

• docs/core/remote_workspace_server_plan.md
• docs/workflow/workflow_scheduling.md

---

Design review update — 2026-07-10

Decision status: architecture discussion only. Do not implement yet.

Key constraint discovered

The local runner may have thousands of arbitrary credentialed CLIs (AWS, Notion ntn, gcloud, and others) while the canonical files live on the server. A generic per-CLI proxy is not a sufficient foundation: although arguments/stdin/stdout can be tunneled, arbitrary programs may open files dynamically, scan directories, follow symlinks, invoke child processes, or create adjacent files.

We cannot simultaneously guarantee all four without a filesystem abstraction:

1. files exist only on the server;
2. arbitrary unmodified local CLIs work;
3. no local mount/cache or temporary materialization exists;
4. coding agents remain unaware of physical file location and execution routing.

Recommended initial architecture

Use an authenticated WebDAV gateway plus an rclone VFS mount on the local runner:

Local coding agent / arbitrary CLI
  -> session-scoped mounted workflow path
  -> rclone VFS cache and lazy reads
  -> authenticated WebDAV
  -> Runloop Remote Workspace Gateway
  -> canonical server workspace-docs

• The frontend and agent_go remain local.
• The server remains a gateway, not a second Runloop control plane.
• The canonical workspace remains plain files on the server for the first version.
• Electron mounts only the selected workflow/session.
• Coding CLIs use the mounted path as their normal cwd and do not need to know whether files are remote.
• rclone handles directory metadata caching, lazy/chunked reads, local VFS caching, and ordinary filesystem presentation.
• A command that reads the entire 50 GB workspace will still necessarily transfer 50 GB; lazy access avoids eager full snapshots but cannot eliminate required I/O.
• Use --vfs-cache-mode full where applications require seeking or random writes.

References:

• https://rclone.org/commands/rclone_mount/
• https://rclone.org/webdav/
• https://pkg.go.dev/golang.org/x/net/webdav

Runloop-specific work still required

rclone/WebDAV solves filesystem presentation and caching, but not product correctness or security. Runloop must still provide:

• SSO/device-token authentication and refresh.
• OS-keychain storage for device credentials.
• Server-derived user identity; never trust caller-supplied X-User-ID.
• Server-side personal/team path mapping, folder guards, and protected planning-file rules.
• Session-scoped mount tokens.
• Workflow write leases with monotonically increasing fencing tokens.
• Scheduled-job claim leases.
• A session staging namespace so cached writes are not promoted piecemeal.
• Atomic validation/promotion of staged changes at commit.
• Lease renewal until rclone has flushed every pending write.
• Crash recovery, unmount, stale-cache cleanup, and rejected stale commits.
• A strict split between remote workspace artifacts and local-only runtime files (tmux recordings, CLI configs, logs, scratch state).
• Server-side SQLite/query handling; do not treat mounted SQLite databases as generally safe concurrent network files.

Operating-system dependencies

• macOS: rclone requires macFUSE, FUSE-T, or its NFS mounting mode, each with installation/behavior trade-offs.
• Windows: rclone mount uses WinFsp.
• Linux: standard FUSE support.

The Electron installer/onboarding must detect, install or clearly guide these prerequisites and verify mount capability before enabling remote mode.

JuiceFS decision

Do not use JuiceFS for the first implementation.

JuiceFS is a later server-side storage option if real usage demonstrates multi-terabyte workspaces, heavy random I/O, or many concurrent clients. It introduces an object store, metadata database, chunked storage format, and materially heavier operations.

If adopted later, keep it behind the same Runloop WebDAV gateway:

Local rclone/WebDAV mount
  -> Runloop gateway with SSO/folder guards/leases
  -> JuiceFS-backed server workspace

Do not connect laptops directly to JuiceFS, because that would complicate or bypass Runloop's device authorization, path mapping, folder guards, and workflow-level lease enforcement.

References:

• https://juicefs.com/docs/community/architecture/
• https://juicefs.com/docs/community/guide/cache/

Explicit non-goals for the first version

• No custom FUSE/cache implementation.
• No adapter ecosystem for thousands of individual CLIs.
• No eager full-workspace checkout.
• No direct frontend connection to a remote agent_go.
• No direct laptop access to JuiceFS/object-store credentials.
• No implementation work until this architecture is reviewed and approved.

Open design questions before implementation

• Which macOS mount backend is acceptable for distribution and permissions?
• Can the gateway expose WebDAV from the existing plain filesystem while preserving atomic staged commits?
• What exact cache limits, encryption-at-rest behavior, and cleanup policy should Electron enforce?
• What happens to an active local process immediately after lease renewal fails?
• Should very large media live directly in object storage with references in workspace-docs?
• Should v1 allow only one active runner per user before shared-workflow concurrency is introduced?

Deployment tenancy assumption

• Deploy one dedicated EC2 instance per customer organization. Unrelated customers never share the same host.
• One customer may have multiple Runloop users on that instance.
• The EC2 instance is the hard cross-customer isolation boundary; do not design a shared multi-customer runner host for this version.
• All users in the customer share the customer workspace and customer-level services, subject to normal role/workflow permissions.
• SSO must still identify the individual user for authorization, audit attribution, approvals, and ownership of interactive sessions.
• Keep tmux/agent sessions and transient runtime state separated by user/session so users do not attach to or steer the wrong terminal.
• Separate per-user credential homes only where credentials are personal. Customer-managed shared credentials may live in a customer-level secret store and be granted by policy.
• CPU, memory, disk, process supervision, and job limits are still required for reliability: one workflow must not kill or starve other users' workflows on the same customer instance.
• Filesystem/process containers are optional hardening inside a customer's instance, not the primary customer-tenancy mechanism.
• Back up durable customer data independently from the replaceable application runtime: snapshot the workspace/data EBS volume and keep tested restore procedures; rebuild the application instance from a versioned image or installer rather than relying only on a whole-instance snapshot.

This assumption makes the server-hosted runner option substantially simpler: agent_go, tmux, coding CLIs, mcpbridge, schedules, and workspace-docs can all run on the same customer EC2 instance without WebDAV/rclone in the execution path. WebDAV/local-runner mode can remain a separate optional architecture if local credentials or laptop-only tools are later required.

[ofekron]

The remote workspace + local runner split is a solid boundary: the server should own authoritative workspace data, leases, audit, and access control, while the local runner owns local authenticated coding-agent execution.

The main risk I would design around is split-brain state. Local plans, schedules, runner status, and remote workspace mutations need explicit acknowledgements and durable IDs so a reconnect can say which actions landed, which are pending, and which must not be replayed. Otherwise the architecture can accidentally become two control planes even if the intent says not to.

I maintain Better Agent, which works on adjacent local coding-agent runtime, provider, workspace, recovery, and backend-owned state concerns: https://github.com/ofekron/better-agent. This comment was drafted with AI assistance and reviewed by me. If useful, a star would help others find the project.