Reference Architecture#

Typical Agent Execution Loop#

Before the workspace pattern, the typical agent execution loop looks like this — a user query is handled by an agent that invokes an LLM, selects tools, runs them in a code-interpreter session (shell, code, filesystem), emits telemetry to an observability plane, and returns the result.

_images/secure-agent-workspace-typical-agent-loop.png

Figure 2 Typical agent execution loop#

The agent, the model call, the tool execution, and the observability plane are all present — but nothing in this picture says where any of it runs, who the agent is authenticated as, what the tools can reach, or how policy is enforced. Those are the questions Secure Agent Workspace answers.

A note on future evolution. Today, the agent, its tools, and the execution context share one workspace VM. A future variant could host the agent in a separate control plane and reduce the workspace to a tool-execution sandbox. Out of scope for this reference design.

Secure Agent Workspace — Where Everything Fits#

The Secure Agent Workspace pattern wraps the baseline loop in a managed environment. User and enterprise services sit outside the VM; Secure Agent Workspace is the thing in between — the integrating concept that gives every part of an always-on agent stack a controlled place to live. Containment from the inside out: agent loop → runtime sandbox → single-user workspace VM → Secure Agent Workspace envelope.

_images/secure-agent-workspace-where-everything-fits.png

Figure 3 Secure Agent Workspace: where everything fits#

Secure Agent Workspace — Seven Logical Planes#

The architecture has seven logical planes. The endpoint attaches, but the workspace executes.

The endpoint is the user’s interface - IDE, terminal, or coding agent. The managed workspace is the execution and policy boundary.

_images/secure-agent-workspace-seven-logical-planes.png

Figure 4 Secure Agent Workspace - seven logical planes#

Architectural Invariants the Design Preserves#

  • The agent never sees raw provider credentials. The credential proxy in Plane 6 rewrites Authorization headers at egress; the agent receives capabilities, not secrets.

  • The agent never reaches an unlisted host. Deny-by-default at both the workspace boundary (Plane 5 → 7) and inside the runtime sandbox (Plane 6). Outbound destinations come from the signed profile allowlist; adding a host is a platform-side allowlist change, not a runtime approval the user or the agent can request.

  • The agent cannot tamper with system binaries. Filesystem is read-only outside the writable agent home; LSM-level enforcement on supported kernels.

  • The host owns the lifecycle. Sandbox creation, policy change, image upgrade are operator actions on the host — not actions the agent can request.

Network Architecture#

Corporate-profile workspaces use an end-to-end brokered network shape — both directions of traffic pass through one trust boundary:

  • Flow 1 (inbound). A consumer reaches the workspace through the trusted access broker over SSH.

  • Flow 2 (outbound). The agent inside the workspace reaches corp-net through the same broker over a per-session reverse tunnel.

The broker is the only path in either direction — nothing reaches the sandbox unbrokered; nothing reaches the corporate network unbrokered.

_images/secure-agent-workspace-network-architecture.png

Figure 5 Secure Agent Workspace - Network Architecture#

From inside the workspace, all internet egress is mediated by the platform-layer egress firewall against an allow-list of approved destinations — source repositories, partner agent endpoints, hosted inference, approved SaaS. Anything outside the allow-list is denied at the platform layer in Phase I; in Phase II the same allow-list is also enforced in-runtime by OpenShell as deny-by-default.

Corporate network resources — internal model service, internal git, ticketing, docs — are not reachable directly from the workspace. The path is workspace → reverse tunnel → trusted access broker → internal jump host → corp service. The jump host is the corporate network trust boundary; every agent reaches the corporate network through it, and the broker multiplexes all per-session reverse tunnels onto the same jump-host pair.

Trusted Access Broker — What It Is and What It Must Satisfy#

The trusted access broker is the single trust boundary between the user’s endpoint and the agent workspace, and between the workspace and the corporate network. It is an enterprise-SSO-backed authentication and session-brokering service, not a VPN or a network appliance — the broker authenticates, scopes, and audits each session; the network path follows.

What the broker does:

  • Authenticates the user against the enterprise IdP (OIDC / SAML), with no alternative path.

  • Issues short-lived, browser-driven sessions to the workspace — no long-lived tokens, no client-side credential storage.

  • Multiplexes per-session reverse tunnels for outbound agent traffic to corp-net (see Network architecture).

  • Audits every session — who connected, when, for how long, from where.

  • Revokes on demand — administrative kill switch can drop active sessions.

What the broker must satisfy:

  • Single path. No alternative network route into the workspace bypasses the broker; bypass = bypass-everything (the architectural invariants in this section depend on the broker holding).

  • SSO-only. The broker has no local user database; identity is upstream.

  • OCSF audit. Every session emits to the enterprise SIEM.

  • Revocation propagation. When SSO entitlement is revoked or the workspace lifecycle API issues a kill, the broker drops the active session within seconds.

Inference — A Hard Dependency, Not a Workspace Feature#

Inference is a hard dependency for any agent loop — every tool call requires tokens. It is not a feature of Secure Agent Workspace itself; the workspace integrates with it. The two are architecturally separate.

Two delivery modes:

  • Local inference. A model runs on a GPU near the workspace. The GPU may be passed through to the workspace VM (with the inference process running in a separate container or namespace from the agent), or held by an adjacent host-level service the workspace calls. Either way, the inference process sits outside the OpenShell / runtime-sandbox trust boundary — the agent can call it, but cannot inspect or tamper with it. Any tampering would break the agent’s own token supply, so isolation protects the agent loop itself, not just the policy enforcement around it.

  • Routed inference (managed endpoint). A model runs in a hosted inference service — internal model service, external LLM gateway, partner endpoint. The workspace reaches it via the credential proxy and routed-inference broker in Plane 6, with the same trust-boundary rule: the agent receives capabilities (the proxy holds the credentials); the inference path is allow-listed at the egress firewall.

GPU acceleration is independent of inference. A workspace may have a GPU for accelerated tools, scientific computing, or vector work without running local inference; a workspace using routed inference may have no GPU at all. Which models, which data classifications, which performance targets, which compliance regimes — that decision tree drives the two choices independently.