Architecture overview¶

Colossus uses ports and adapters with explicit inward dependency direction. Domain contracts do not depend on infrastructure, and user interfaces never own model, tool, policy, workflow, or persistence behavior.

flowchart LR
    subgraph Interfaces
      CLI["CLI"]
      TUI["TUI"]
      SDK["Application SDKs"]
    end
    subgraph Transport
      GRPC["Authenticated loopback gRPC"]
      Worker["Worker host"]
    end
    subgraph Composition
      Runtime["Runtime composition"]
    end
    subgraph Application
      Agent["Agent and application services"]
      Ports["Application ports"]
      Contracts["Contracts"]
      Domain["Domain"]
    end
    subgraph Adapters
      Provider["Providers"]
      Journal["ephemeral/file redb or PostgreSQL"]
      Sandbox["Sandbox and effect adapters"]
      Extensions["Integrations, MCP, Agent Plugins"]
    end

    CLI --> Runtime
    TUI --> Runtime
    SDK --> GRPC
    GRPC --> Worker
    Worker --> Runtime
    Runtime --> Agent
    Agent --> Ports
    Ports --> Contracts
    Contracts --> Domain
    Runtime --> Provider
    Runtime --> Journal
    Runtime --> Sandbox
    Runtime --> Extensions
    Provider --> Ports
    Journal --> Ports
    Sandbox --> Ports
    Extensions --> Ports

Reading the diagram without color: interfaces enter the composition root; application services depend inward through ports, contracts, and the dependency-free domain; infrastructure adapters implement ports and are assembled only by the runtime.

Workspace layers¶

Boundary rules¶

The cloud control plane is a separate application composition. Its Diesel/diesel-async PostgreSQL schema and database-backed user and project authority are independent of runtime journals and policy. colossus-cloud-postgres owns pooled relational storage, transactional outbox/audit records, shared browser sessions and fenced connection leases. Host/agent/workspace grouping and thread history do not grant local execution authority. Each connector uses a dedicated native application grant; it cannot borrow the Desktop primary or approval-broker credential. Cloud roles intersect that grant and never expand local tool, policy, or sandbox authority. The closed remote operation set does not expose private worker RPC, arbitrary network forwarding, or renderer credentials.

Manual Desktop credentials and platform-backed MCP OAuth share the colossus-credentials adapter. HostSecret (64 KiB) and VaultRecord (1 MiB) are non-serializable, zeroizing contracts. CredentialVault and its opaque record identities belong to the ports surface; categorical credential errors are shared with contract validation. Runtime composition injects the vault into MCP; the adapter owns neither OAuth protocol behavior nor authorization policy.

Each owner lazily opens one credentials-v1.redb and companion lease file within its validated private root. Desktop manual credentials use the global Desktop directory; platform OAuth uses the isolated runtime state directory. Conversation, journal, and settings databases contain no credential records. Native Windows and macOS entry lives in the private apps/desktop/native-credential-ui crate; Tauri commands dispatch it without receiving secret values from the renderer.

• colossus-domain has no dependencies.
• Ports are owned by the application, not infrastructure.
• The runtime owns adapter construction and opaque permit-bearing executors.
• Runtime composition canonicalizes one explicit workspace. CLI -w, --workspace, embedded open options, and worker workspace matching all feed the same repository context and state identity. An isolating execution boundary may confine resources to it; acknowledged full access deliberately does not.
• Shared CLI and TUI home resolution selects absolute COLOSSUS_HOME or the platform user home, validates its owner-private no-follow boundary, and derives one opaque partition from canonical workspace path and object identity. Linux keeps the birthtime-based identity when available; an NFS workspace that does not report birthtime uses a distinct filesystem-scoped opaque-handle identity captured from the same opened directory. Missing, malformed, inconsistent, or unsupported identity evidence fails closed. Windows Desktop honors an explicit COLOSSUS_HOME; otherwise its native composition selects the fixed owner-private ColossusDesktopHome beneath the user's local application-data directory. Interfaces consume the resolved context; renderer code never invents configuration or state paths.
• Configuration resolution selects one explicit, repository-local, or user-level document without merging. Runtime composition receives the selected source and resolved storage path after storage.location confinement has succeeded.
• CLI/TUI and Desktop use distinct children of the same workspace partition. Their database leases, worker identities, provider credentials, and lifecycle ownership do not cross interface boundaries.
• Access resolution produces visibility and action decisions; execution-boundary and sandbox-profile resolution independently produce explicit, derived, or ambient resource obligations. Ambient obligations remain request-bound and require the acknowledged danger runtime envelope.
• CLI and TUI construct requests, invoke application services, and render typed results.
• A released ToolResult is the complete run-facing result used by terminal events and run evidence. The agent derives a separate bounded, parseable tool observation for model continuation and session history. Each observation is limited to 64 KiB and every tool observation between two user messages shares one 256 KiB logical-turn budget, including results separated by assistant continuations. colossus-tools owns that projection; colossus-context reapplies it when preparing legacy session history so sequential tool batches cannot make the newest logical turn impossible to compact.
• Desktop persists folder-backed WorkspaceProfile records and presents them as Workspaces. One natively selected Workspace projects its workspace, provider/model, access, execution-boundary, and terminal configuration into the existing command boundary; renderer actions cannot nominate a background Workspace. A native manager may retain up to four independently supervised sidecars and evicts only the least-recently-used idle entry.
• Desktop Asides create a separate session through the exact canonical end of the selected source run. The renderer supplies only that owned run identity; the runtime resolves the message boundary so a visible final response cannot be omitted by an incomplete activity-feed projection. The sidecar materializes a conversation projection containing visible user and assistant messages only; system messages, assistant tool-call records, tool results, and their payloads are not copied into the Aside.
• Desktop workspace browsing remains an interface-only, read-only view. Its native commands accept the opaque selected-Workspace identity plus a validated relative path; they do not add model, tool, policy, state, or mutation logic to the renderer.
• Desktop Git inspection is a read-only human surface with a private native Git reader. Repository handles bind the selected workspace and validated metadata directories; no Git execution or write capability is exposed. See ADR 0004.
• Desktop file search and text diffs reuse the same native workspace/Git authority. The read-only renderer owns presentation and bounded document lifetimes; see ADR 0005.
• Desktop's opt-in browser preview is a separate human browsing surface. Native session/tab state and engine integration stay in the Desktop browser manager and private native adapter. Guests receive no application capability. Future browser automation requires a runtime port with policy and audit; see ADR 0003.
• Desktop's native Managed Local permission selector uses the narrow authenticated colossus-worker-protocol control client. The Desktop process does not link runtime, model, tool, policy, or worker-host implementation crates.
• Desktop Codex account commands remain native interface adapters: they delegate login and logout to colossus-codex-auth, while runtime/provider construction stays in the sidecar and colossus-runtime. The renderer receives status only.
• Provider setup choices belong to the shared credential-free contracts catalog. CLI and Desktop expose these presets separately from Chat Completions, Responses, and Codex protocols. Catalog discovery runs through the existing runtime provider effect gateway, including before a model is selected; an offline echo route allows the connection to be inspected without a fabricated model ID or generation. Provider adapters normalize bounded, optional model-card metadata. Missing limits or capabilities remain distinguishable from provider-declared values, and model selection never grants tools or changes policy based on remote descriptions.
• Desktop setup packages are native interface imports: setup_package bounds and reviews an offline ZIP manifest, assets, and provider/model YAML. The verified sidecar's existing inspection API validates runtime semantics; no runtime crate is linked into Desktop. Saved setup metadata is separate from active workspace configuration. Credentials, trust changes, and model activation reuse existing native services and persist through the version-7 Desktop settings envelope.
• Disposable Desktop setup diagnostics bind their protected journal identity to the canonical runtime directory and its filesystem identity. Versioned migration moves setup to a new namespace without resetting or bypassing workspace journal anchors. Windows NSIS cleanup is a native-only entry point with a fixed default-home scope; it reads bounded ownership metadata, removes exact OS key accounts, and refuses reparse points, active files, or shared CLI state. Plugin cache hard links are allowed only when every filesystem name belongs to an inspected blob in that cache; external aliases and links involving other data remain protected. It is not a renderer command.
• Top-level user-facing runs snapshot bounded home and repository AGENTS.md instructions before provider execution. Goal iterations and delegated subagents carry that immutable snapshot and provenance; internal risk, summarization, and diagnostic model roles do not consume it.
• Delegated child jobs remain durable work records, while their scheduler runs alongside the parent provider/tool loop instead of suspending it. The scheduler continuously fills newly available subagents.maxConcurrent slots as later delegates arrive. Streaming parent runs receive bounded durable child lifecycle updates, including the released terminal result, over the same ordered run-event boundary used by CLI, TUI, worker, and public application adapters.
• External applications enter through the authenticated public worker API or a caller-bound embedded SDK backend; they never depend on agent internals.
• Crate roots expose a focused API or composition surface; nontrivial logic belongs in named modules.
• Runtime canonical writes append journal events. Runtime read models and indexes are replaceable. Cloud domain state uses independent relational transactions with audit, outbox, and source cursors.
• Event-sourced repositories discover aggregate streams through bounded pages of the journal-maintained stream identifier index. Listing integrations, plugin installations, sessions, work, research, memory, or workflows must not rescan the global event history.
• Public run creation atomically appends its per-application owner-index entry; ListRuns traverses that index newest-first instead of scanning the shared journal.
• The complete effect path is centralized; an adapter cannot mint its own authority.

See Rust crate structure for module and public-surface conventions, Runtime and ports for service ownership, and Public API and application SDKs for external application integration. See Security architecture for the effect boundary.