Workspace Files & Pre-Gateway: Routing to the Right Container, Landing on the Right Disk

Incident: Publish Success but IDE Shows Stale Files

A pipeline reported "publish successful" yet the author's IDE displayed three-day-old files. Clearing caches, switching browsers, and re-logging did not help. Root cause: the publish wrote to the shared filesystem path, but the request was routed to a container that did not mount the same volume. The IDE was correct; the machine simply lacked the expected disk.

Runtime answers "where code executes"; this article answers "where file truth lives, and whose disk you see when routing goes wrong".

Key Terms

Workspace : Agent's file truth — code, knowledge, artifacts all inside.

Shared filesystem (mounted disk) : Network filesystem for dev mode, mounted at container start; multiple containers can mount the same volume.

Object storage : Storage service for runtime, read/write by object, no mount needed.

File proxy : Co-located execution service that does heavy I/O (packaging, preview), not chat.

Site gateway : Handles static resources and site entry; decides "can the site open".

Pre-gateway : Handles auth, container selection, address resolution; decides "which container to enter".

location : Reverse proxy bucketing rule — chat, IDE, sync port, file proxy each go their own way.

Container shape : Dev (writable build disk), runtime (runs user chat), pooled (pre-warmed headless instances).

Sync sidecar : Small process beside container, handles upload and restore sync actions.

(Sidecar, ACL, RPC, IDE, Web IDE are standard terms not explained here.)

01 | Before Doing Work, Ask "Where's the Disk?"

Think of the system as a library :

Building door / access control → Site gateway: governs "can the hall open".

Internal signage / front desk → Pre-gateway: governs "which reading room you go to".

Open stacks (grab and edit directly) → Dev-mode shared filesystem mount.

Closed stacks (need request slip) → Runtime object storage.

Librarian (fetches, packages books) → File proxy: only does I/O, no chat.

Door broken → Site won't open.

Signage points to wrong room → Site opens, but chat / IDE / file read all fail.

The "publish green, IDE shows old files" incident maps perfectly: books were placed in Library A's open stacks, but signage sent the reader to Library B — which didn't have those books. The IDE was right; the user just walked into the wrong room.

This analogy also explains two more things:

Open and closed stacks are two services, don't force unification. Letting readers wander into closed stacks (runtime mounting dev volumes) kills stack turnover; locking everything in closed stacks (global object storage) loses the "grab and edit" experience of open stacks.

Librarians don't write books, they only fetch. File proxy is a same-region worker; it doesn't join chat, only guarantees disk actions happen in the right place.

Agent demos often fool acceptance with "workspace has code". Three follow-ups expose gaps: can runtime see dev-edited files? Where does publish fail? Do web preview and IDE open the same mount point?

One "edit file" request — which doors does it pass?

Three Typical Scenes

Scene A: Publish success, IDE still old

Surface symptom: "Cache not flushed"

Common misdiagnosis: Clear browser, re-login

Mechanism truth: Publish wrote to shared FS path, request went to container without same volume mount

Scene B: Runtime chat opened but missing knowledge files

Surface symptom: "Packaging missed"

Common misdiagnosis: Republish

Mechanism truth: Runtime doesn't read dev mount directly; two storage paths are isolated

Scene C: Site opens, all files 502

Surface symptom: "Gateway down"

Common misdiagnosis: Restart frontend traffic gateway

Mechanism truth: Site gateway fine; pre-gateway container selection or file proxy same-region I/O failed

First door to doing work isn't the model, it's "request enters right container, file lands on right disk". Pick wrong container, pick wrong entire disk life.

02 | "Container Has a Workspace Directory" Is Far From Enough

Compressing file problems into "create a directory in container" fractures at three layers.

Two Gateways Collapsed Into One Term

Opening site uses site gateway; entering chat, opening IDE, syncing workspace, calling file proxy use pre-gateway . Former handles static and entry reverse proxy; latter handles auth, container selection, address resolution, location-based bucketing reverse proxy. Mixing troubleshooting terms leads to "site 200 but chat all red" then debugging wrong cluster.

Dev and Runtime Drawn as Same Arrow

Dev, collaboration, evolution containers usually mount shared FS: need mount, rely on same-region file executor for publish distribution. Runtime resident sidecars are thinner, chat-runtime centric, file truth more in object storage plus container workspace, version sync via sidecar. Forcing "unified storage" either drags down runtime density or makes dev lose IDE writable mount experience.

Orchestration Process Directly Chews Disk

Orchestration brain and shared FS may be in different regions. Large file preview, state query, publish packaging — if placed in orchestration process for direct read, latency and bandwidth become hidden tax. Correct division: path assembled by orchestration authority, I/O delegated to same-region file proxy — it's not a chat service, it's a dedicated worker.

In evaluations we steal "pre-gateway picks container + dual storage tracks + same-region file proxy"; reject "one workspace directory rules all"; reject "site gateway doubles as container picker".

Container local empty dir as workspace : steals demo fast; rejects publish, collaboration, cross-instance consistency.

Global unified object storage : steals ops simple; rejects dev-mode IDE mount experience.

Global unified mounted disk : steals IDE nice; rejects runtime density and recycle cost.

Split storage + gateway picks right container : steals both sides work; rejects must explain two stories clearly.

03 | Enter Right Container × Land on Right Disk × Same-Region Execution

Gateway is signage, mounted disk is dev floor, object storage is warehouse — miss one, workspace is just a slogan.

Routing layer (Where) : After auth, which container, which port, which location class. Solves: requests don't cross disks, don't cross shapes.

Storage layer (What) : Dev mount path authority; runtime object storage & sync; publish packaging pipeline. Solves: file truth updatable, recoverable, auditable.

Connection rules per text: Chat runtime and workspace sync port use "runtime: object storage"; Web IDE and file execution proxy use "dev: shared filesystem mount".

Enter right door first, then stand on right floor — publish writes disk and chat reads disk are two causal chains, finally accountable to same truth.

04 | Pre-gateway: Enter Right Container

🎯 Challenge : Same agent — workspace edit, headless chat, pooled pre-warm, file proxy call — target processes completely different.

💡 Solution : Pre-gateway does one target resolution after auth: by location and deploy shape pick service and port, then resolve to a live instance.

Five Location Classes (External View)

Chat → Container chat runtime → Start chat, stop, resume, pre-warm

Web IDE → IDE runtime port → Edit code in browser

Workspace sync port → Sidecar sync service port → Upload and restore actions

File proxy → Independent file execution service → Publish packaging, mount-side preview and execution

Container management port → Container management port → Health check, sandbox packaging

Different location, different upstream port and identity headers. Using "one reverse proxy rules all" feeds IDE requests to chat port — symptom looks like random 404, root cause is collapsed routing table.

Pick Container: Dev First, Then Pooled and Shared

Same caller hitting same agent may still enter different container shapes:

Dev : writable build disk, usually with IDE and sync sidecar

Pooled : pre-warmed headless instances after binding

Shared / Visitor : legacy or special shapes

Within permission scope, dev often prioritized — it targets "the disk being built or collaborated on"; if not hit, fall back to deploy mode for pooled or shared shunting. Wrong branch shows as "files lost" to user. Auth failure and "no available container" must be distinct error codes: former is user problem, latter is pool problem.

// Illustrative · TypeScript
// Guarantee: when in scope and want to write build disk, dev first
type DeployHint = "develop" | "pool" | "shared_or_visitor";

function pickContainer(opts: {
  inScope: boolean;
  preferDevelop: boolean;
  deployMode: "container" | "pool";
}): DeployHint {
  if (opts.inScope && opts.preferDevelop) return "develop";
  if (opts.deployMode === "pool") return "pool";
  return "shared_or_visitor";
}

# Illustrative · Python
# Guarantee: same, shape decision centralized, not scattered across call sites
def pick_container(in_scope: bool, prefer_develop: bool, deploy_mode: str) -> str:
    if in_scope and prefer_develop:
        return "develop"
    if deploy_mode == "pool":
        return "pool"
    return "shared_or_visitor"

Two Gateways Compared, Must Distinguish

Site gateway : governs site open, static, entry reverse proxy. Broken feels like page won't open. First debug question: domain and static hit? Analogy: building access control broken.

Pre-gateway : governs which agent container to enter. Broken feels like site opens but chat / IDE / file read fail. First debug question: auth, container pick, address resolve stuck where? Analogy: access control fine, but signage points to wrong room.

🛡 Boundary : Pre-gateway doesn't invent storage topology; it only guarantees "this request enters the right door". What the disk is, next section covers.

05 | Dual Storage Tracks: Dev Mount vs Runtime Object Storage

🎯 Challenge : One storage service for all shapes — either expensive or hard to use.

💡 Solution : Dev uses shared FS mount, runtime uses object storage plus container workspace, publish and sync pipelines ferry truth between them.

Dev: Mount + File Proxy

Path assembled by orchestration side authoritatively (by platform routing disk entry and container logical root), mounted into workspace at container start. Publish must not let orchestration process cross-region read/write large files; instead call file proxy to complete pipeline in same region:

Package source tree by include/exclude rules

Transfer to target workspace side

Reset target directory (can rename to recycle bin)

Unpack

Restore preserved paths (avoid wiping user local state)

Clean temporary artifacts

Publish feels irreversible, so support dry_run: only rehearse stages and commands, no side effects. Canary period uses it to see hit rate, not users as guinea pigs.

File proxy is same-region worker: it doesn't chat, only guarantees disk actions happen in the right place.

Runtime: Object Storage + Container Workspace

Runtime instance sidecars are thinner, often chat-runtime centric. Knowledge and versions sync into container workspace via object storage; dev or evolution container sidecars handle upload/restore sync ports. Reading runtime config (e.g., model manifest) uses runtime sandbox file preview, not dev mount direct-read function. Mixing the two paths produces "dev has, runtime missing" ghost faults.

Comparison

Main storage : Dev — shared filesystem (needs mount); Runtime — object storage + container workspace

Sidecars : Dev — chat runtime + IDE + sync sidecar; Runtime — chat runtime mainly

Update workspace : Dev — publish pipeline via file proxy; Runtime — sync, packaging, sandbox paths (different chain from publish)

File proxy : Dev — main force for publish and mount-side I/O; Runtime — not resident by shape, invoked on demand by orchestration

Gateway key : Dev — easy enter dev + IDE location; Runtime — easy enter pooled instance + chat location

// Illustrative · TypeScript
// Guarantee: runtime config doesn't read via dev mount direct
type FileChannel = "mount_via_file_agent" | "object_store_sidecar" | "runtime_sandbox_preview";

function channelFor(kind: "dev_preview" | "dev_publish" | "usage_config"): FileChannel {
  if (kind === "usage_config") return "runtime_sandbox_preview";
  return "mount_via_file_agent";
}

# Illustrative · Python
# Guarantee: channel forks by shape, error codes reveal which path taken
def channel_for(kind: str) -> str:
    if kind == "usage_config":
        return "runtime_sandbox_preview"
    return "mount_via_file_agent"

🛡 Boundary : This piece covers disk topology and routing. "Who can write which directories, how role knowledge is trimmed" belongs to security chapter — first land on right disk, then talk ACL.

06 | Two Scenario Validations: Signage + Floor

Scene A: Dev Publish, IDE Immediately Readable

Path: Policy triggers publish → orchestration orders → file proxy same-region executes packaging distribution → shared FS updates → pre-gateway routes IDE and workspace requests into container mounting same volume.

Decision points:

A : Orchestration process directly reads/writes disk.

B : Path computed by orchestration, I/O by file proxy.

Choose B. Cross-region large file I/O is chronic poison.

Scene B: Runtime Chat Reads Publish Artifacts, But Cannot Enter Dev Mount Path

Path: User starts chat → pre-gateway picks pooled or runtime container → runtime reads container workspace (synced from object storage or publish artifacts landed) → forbid mistakenly taking dev mount preview channel.

Decision points:

A : Runtime and dev share one "read file" internal implementation.

B : Channels fork by shape, error codes reveal which channel taken.

Choose B. Same-named interface, different paths — friendship boat of debugging.

End-to-End Checklist

Two gateways : Site-open failure and container-entry failure debuggable with different terms

Container pick : Dev / pooled / shared visitor explainable, failure codes distinguishable

Dev disk : Mount exists; publish stages observable (package / transfer / …)

Runtime disk : No dependency on mount direct-read; sync or sandbox paths nameable

File proxy : Not treated as chat upstream; same-region, supports dry_run

07 | Cost and Selection of This Design

⚡ Quantified efficiency : After killing wrong-container picks and cross-region direct reads, "ghost old files / preview timeout" tickets converged noticeably (mechanism comparison)

📥 Capability sunk : Frontline can directly ask "is this mount issue or object storage sync issue" without memorizing internal repo names

📚 Pattern upgrade : From "container has a directory" to "routing × dual storage × same-region execution"

Five-Dimension Selection

Dev IDE : Single local dir — Poor; Global object storage — Medium; Global mount disk — Good; Dual-track + pre-gateway pick — Good

Runtime density : Single local dir — Good; Global object storage — Good; Global mount disk — Poor; Dual-track + pre-gateway pick — Good

Publish consistency : Single local dir — Poor; Global object storage — Medium; Global mount disk — Good; Dual-track + pre-gateway pick — Good

Debuggability : Single local dir — Poor; Global object storage — Medium; Global mount disk — Medium; Dual-track + pre-gateway pick — High

Recommended : Single local dir — Demo only; Global object storage — Runtime-biased; Global mount disk — Dev-biased; Dual-track + pre-gateway pick — Default

08 | Where Not Applicable, Four Pits and How to Split

Applicable / Not Applicable

Applicable : Agent platforms with dev/runtime split shapes, need publish to running instances; Need IDE mount and headless chat coexist.

Not applicable : Local demo where single dir is truth; Pure Q&A bots with no file side effects.

Pit 1: Using Site Gateway Timeout to Rescue File Proxy

Trigger : Both called gateway. Wrong antidote : Crank up frontend traffic gateway read timeout. Right antidote : Budget site-open and container-entry separately; large package publish watches file proxy and orchestration timeouts. Back to library: If door lock broken you fix lock; if signage points wrong room you change sign — loosening main door closer doesn't fix reader walking into wrong reading room.

Pit 2: Runtime Mounts Dev Same Volume

Want "one file visible both places", so mount shared FS on runtime instances. Result: density and recycle cost spike, and runtime shouldn't depend on mount anyway. Library equivalent: **letting every reader enter closed stacks to browse — turnover collapses, and stacks weren't for readers to wander.** Right way: runtime uses object storage, sync, sandbox paths; dev uses mount; both ferry truth via publish and sync.

Pit 3: Orchestration Process Directly Reads Large Files on Mount

Trigger : Save one remote call, implement fast. Wrong antidote : Preview large files, cross-region drags orchestration process dead. Right antidote : Path authority stays in orchestration, I/O to same-region file proxy.

Pit 4: Treating Publish and Chat Read/Write as Same Interface

Both superficially "modify workspace", so merged into one handler with shape-based branching — result: stage failures never separable. Right way: publish pipeline and chat read/write as two causal chains, meeting only at disk truth and audit.

L1 / L2 / L3 Governance

L1 : Routing error codes, publish stage metrics, dry_run canary — approved by platform team

L2 : Add location / add sync channel — cross-gateway and orchestration review

L3 : Storage track semantics change (e.g., runtime switches to mount) — change gate + capacity assessment

Summary

Before doing work, ask where's the disk: enter right container, land on right disk, precedes model intelligence.

Site gateway and pre-gateway are not the same; mixing terms guarantees debugging wrong layer.

Dev uses shared FS mount, runtime uses object storage plus container workspace — two backbones, don't draw as one arrow.

File proxy is same-region worker: path orchestration computes, I/O proxy executes.

Wrong container equals wrong disk; dev vs pooled shunting must be explainable.

Publish writes disk and chat reads disk are two causal chains, converge at disk truth; who writes which directories goes to security chapter.

Gateway is signage, mount is floor, object storage is warehouse — enter right door first, then stand on right floor.