docs(architecture): Layer 6 — C4 Container (seven containers)

[Yambr]

What

The container view of the OCU box that Layer 4 drew as one block — seven containers across the six trust zones.

The Control plane splits into two containers on its interface seam: an agent-facing MCP gateway and an operator/lifecycle API. The kill-switch lives only on the operator API, unreachable from the agent path by network policy — a deploy-time fact, not an in-process route guard. The other five zones map 1:1, including the Storage broker as its own container.

Seven containers: MCP gateway · Control / operator API · Credential custody · Storage broker · Session sandbox [1..N] · Egress trust-edge proxy · Audit pipeline.

Faithful to the current model

• Edges match the §8 token taxonomy: Session JWT bound to container_name (≤60 min, host dials guest), custody credential lease (≤15 min, held by the egress edge — never the guest), storage-mount handle (filesystem_id).
• Host-attested control channel, off the guest network ([NFR-SEC-43]).
• Storage broker on both legs: the guest mount (inbound) and the broker-signed backend request through the egress edge in allow-list-only mode (outbound).
• §6 states where OCU's decomposition diverges from the industry shape (storage broker as its own container; egress as a credential-injecting chokepoint) for an in-perimeter regulated threat model.

Notes

• The diagram lives only in diagrams/c4-container.mmd; the doc links it (no inline duplicate).
• Open seam questions deferred to component specs: sandbox sub-split (arch: Session sandbox — single container vs sub-container split (C4 Container) #174), custody/broker per-deployment-vs-per-host (arch: Credential custody — deployment cardinality (one per deployment vs per sandbox host) #175).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added draft container-style architecture docs and accompanying visual diagram showing seven runnable containers, trust zones, token/event flows, and audit fan-in.
  • Clarifies runtime boundaries and per-session sandbox responsibilities, deployment "minimal" vs "full" shelves, credential/egress constraints, and includes two tracked open questions with review/applicability metadata.

[coderabbitai]

Warning

Review limit reached

@Yambr, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 16 minutes and 35 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ba488d45-2f85-4930-9c2d-40bcc505efc5

📥 Commits

Reviewing files that changed from the base of the PR and between 2998c60 and 7cf0e43.

📒 Files selected for processing (2)

• docs/architecture/05-c4-container.md
• docs/architecture/diagrams/c4-container.mmd

Walkthrough

Adds a draft C4 container-level architecture document and a canonical Mermaid container diagram for OCU, defining seven runnable containers, their responsibilities, named token/protocol boundary crossings, deployment "minimal vs full" shelves, internal security invariants, and two tracked open questions.

Changes

C4 Container Architecture

Layer / File(s)	Summary
Container architecture model and metadata docs/architecture/05-c4-container.md	Adds SPDX header, draft metadata, audience framing, and maps C4 containers to trust zones and bounded contexts.
C4 container diagram (file) docs/architecture/diagrams/c4-container.mmd	Adds the canonical Mermaid C4 container diagram file with seven internal containers, external orientation nodes, and labeled edges for authz, session lifecycle/JWT, storage mounts, egress credential leases, and OCSF audit fan-in.
Container responsibilities and guest-agent note docs/architecture/05-c4-container.md	Documents seven containers with responsibility/NFR anchors and clarifies the guest agent runs as the process inside the Session sandbox container (not a separate container).
Internal boundaries and sandbox isolation docs/architecture/05-c4-container.md	Enumerates boundary-crossing artifacts (Session JWT bound to container_name, file-operation mounts, credential lease injection, single outbound path) and records invariants preventing guest access to standing secrets and kill-switch impersonation; separates storage-mount vs egress paths.
Deployment topology: minimal vs full shelves docs/architecture/05-c4-container.md	Defines two deployment "shelves" describing substrate/placement differences for the same seven containers while preserving responsibilities (minimal co-located shelf vs full distributed shelf with optional audit sink).
Industry comparison & open questions docs/architecture/05-c4-container.md	Adds an industry comparison highlighting OCU divergences (Storage broker isolation; Egress as credential-injecting enforcement chokepoint) and records two open questions with issue links.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Wide-Moat/open-computer-use#177: Aligns egress trust-edge and credential custody behavior (Session JWT binding and custody-issued lease injection) described in this C4 doc/diagram.
• Wide-Moat/open-computer-use#189: Related Layer-3 structure and Storage broker trust-zone modeling that this container view formalizes.
• Wide-Moat/open-computer-use#172: Aligns sandbox/egress/audit boundary assumptions and LLM/egress allow-listing constraints referenced by this PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: addition of Layer 6 C4 container architecture documentation defining seven concrete containers. It is concise, descriptive, and directly reflects the primary objective of the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/layer6-c4-container

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/architecture/05-c4-container.md (1)

54-54: 💤 Low value

Clarify the statement about external actors.

The text states "this view does not redraw them [external actors]," but the diagram explicitly renders PEER, UP, and SINK (and the canonical .mmd also includes OPER). Consider rephrasing to clarify that external actors are shown for context but their detailed contracts are defined in the referenced Layer 3 document.

📝 Suggested clarification

-Canonical source: [`diagrams/c4-container.mmd`](diagrams/c4-container.mmd). Edge labels name the protocol or token class that crosses; `1..N` marks the per-session container. The four Agent-Execution containers fan into the Audit pipeline over one Published Language (OCSF) — drawn as four edges, one label. External actors and their contracts are in [`03-c4-context.md`](03-c4-context.md) §4; this view does not redraw them.
+Canonical source: [`diagrams/c4-container.mmd`](diagrams/c4-container.mmd). Edge labels name the protocol or token class that crosses; `1..N` marks the per-session container. The four Agent-Execution containers fan into the Audit pipeline over one Published Language (OCSF) — drawn as four edges, one label. External actors are shown for orientation; their detailed contracts are defined in [`03-c4-context.md`](03-c4-context.md) §4.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture/05-c4-container.md` at line 54, Update the sentence that
currently reads "this view does not redraw them" to clarify that external actors
(PEER, UP, SINK, and OPER as shown in diagrams/c4-container.mmd) are rendered
only for contextual reference while their detailed contracts remain defined in
03-c4-context.md §4; change the wording to something like "External actors
(PEER, UP, SINK, and OPER) are shown here for context, but their detailed
contracts are defined in 03-c4-context.md §4" so readers know the diagram
includes actors visually but the authoritative contract information lives in the
Layer 3 document.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/05-c4-container.md`:
- Around line 24-52: The Mermaid diagram is missing the Operator actor and its
PAM-JIT edge; add an OPER node (label like "Operator / PAM-JIT human") to the
flowchart and the edge OPER -->|"PAM-JIT credential"| CP so the diagram matches
the canonical diagram (ensure the new OPER node uses the same styling pattern as
other actors like PEER/UP/SINK and place the edge pointing to CP).

---

Nitpick comments:
In `@docs/architecture/05-c4-container.md`:
- Line 54: Update the sentence that currently reads "this view does not redraw
them" to clarify that external actors (PEER, UP, SINK, and OPER as shown in
diagrams/c4-container.mmd) are rendered only for contextual reference while
their detailed contracts remain defined in 03-c4-context.md §4; change the
wording to something like "External actors (PEER, UP, SINK, and OPER) are shown
here for context, but their detailed contracts are defined in 03-c4-context.md
§4" so readers know the diagram includes actors visually but the authoritative
contract information lives in the Layer 3 document.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0980f265-62df-4c44-b20a-3d6c10ec69e3

📥 Commits

Reviewing files that changed from the base of the PR and between 256a4f3 and d84dd5c.

📒 Files selected for processing (2)

• docs/architecture/05-c4-container.md
• docs/architecture/diagrams/c4-container.mmd