Architecture Deep Dive

This page describes how the current UnisonOS stack is wired end-to-end in the devstack and platform compose.

End-to-End Flow (Input → Intent → Outcome → Render)

  1. Input arrives from an I/O service (speech, vision, BCI, etc.), the experience renderer, or an actuator (Agent VDI).
  2. Intent Graph normalizes the request and forwards it to the orchestrator.
  3. Orchestrator coordinates the turn:
  4. Reads/writes profile and session state via Context.
  5. Enforces Auth, Policy, and Consent for sensitive actions.
  6. Calls Inference when generation or planning is needed.
  7. Routes to tools/services (for example: Storage, Comms, or actuation via Agent VDI).
  8. Results are returned as structured outputs (and storage references for artifacts), then rendered by the experience renderer in real time.

Envelopes and Service Contracts

Unison services share a small set of consistent patterns:

These envelopes allow the orchestrator to reason over heterogeneous tools while keeping governance (policy/consent/audit) centralized.

Shared Library: unison-common

Most Python services in the stack share a common runtime library: unison-common.

What it provides today:

Where to look:

Persistence and Messaging (What Runs Under the Hood)

In current deployments:

Devstack vs Platform Compose

Security and Governance Boundaries

Edge-First and Optional Cloud

UnisonOS is designed to run primarily on edge devices. Cloud connectivity is optional and must be explicitly configured, auditable, and consent-aware.

Edge First Runtime

Optional Cloud Inference

Profile Sync (Current Status)

Components (Current Stack)

Core control plane:

State and data:

Actuation and I/O:

Infrastructure commonly used:

System Capabilities (Resolver, Manifests, and Safe Execution)

UnisonOS uses a capability system to connect intents to concrete tools, connectors, MCP servers, and skill packs. This system is designed to keep execution policy-governed and auditable, and to prevent ad-hoc “direct tool calls” that bypass platform controls.

Authority model (planner contract)

At a high level:

This separation is what allows UnisonOS to add new tools and integrations without expanding the trusted surface area of the orchestrator itself.

Capability lifecycle (end-to-end)

In a compliant flow:

  1. Planner calls capability.search(intent, constraints) to discover candidates.
  2. Planner calls capability.resolve(step) to select/validate a concrete candidate.
  3. Planner calls capability.install(candidate) if the capability is not already available locally (and policy allows).
  4. Planner calls capability.run(capability_id, args) to execute.
  5. Resolver persists state and exposes inventory operations (capability.list/get/remove).

Manifests: the source of truth

Capabilities are declared in a manifest and validated against a platform schema before being persisted or executed. A manifest describes:

Seeded capabilities: base + local layering

Images can ship with a curated baseline manifest:

Resolver view = merge(base + local), where local overrides base entries by id. Runtime writes (installs, enablement changes, secret bindings) always go to the local manifest.

This makes “out-of-the-box” experiences fast (common local tools resolve immediately), while still allowing safe customization and resets (local state can be cleared without modifying the shipped baseline).

Connectors, OAuth onboarding, and secrets (no secrets in manifests)

Network connectors (email/calendar/chat/etc.) are typically shipped disabled by default and require explicit onboarding:

Egress controls and runtime enforcement

All outbound calls for registry discovery, OAuth, MCP tool invocation, and A2A delegation are expected to pass through a single egress control point:

Storage and Persistence

Storage is the unified persistence layer for UnisonOS artifacts and durable service records. It provides a single API for:

In current implementations, the storage service persists metadata to Postgres (required in production; SQLite is only allowed for local/dev), and stores object payloads on the local storage volume.

Responsibilities:

Security and privacy:

Actuation (VDI and VPN)

Actuation is the layer that allows UnisonOS to cause effects in external systems beyond returning text or speech. Actuators are governed by policy and consent.

VDI provides a headless desktop/browser environment used for GUI-style web flows (multi-page sites, downloads, workflows that lack APIs).

VPN boundary:

Intent → VDI flow (high level):

  1. Intent arrives and is normalized into an envelope.
  2. Orchestrator checks policy/consent.
  3. Orchestrator emits an Action Envelope describing steps.
  4. Actuation selects VDI when a browser/desktop workflow is required.
  5. VDI executes steps and writes artifacts to storage.
  6. Results return to the orchestrator and are rendered in the experience.

API details live in Reference → APIs.

Inference and Model Execution

Inference is a dedicated service that runs models and exposes a stable API to the rest of the platform. Providers are swappable behind the inference boundary.

Inference routes each bounded interpretation, extraction, vision, semantic construction, synthesis, or conversation operation independently. Candidates come from a signature-verified registry. Hard eligibility evaluates task and structured-output support, privacy and disclosure, risk, offline state, hardware compatibility, measured latency, cost, license, artifact integrity, and support status before an inspectable person-aligned ranking is applied.

Model-assisted semantic output uses a typed, provenance-bearing proposal that is always untrusted. Deterministic services reconcile source versions, exact facts, recipients, actions, recovery, and required meaning. High-risk and exact content uses a deterministic language path.

New versions pass golden semantic journeys in shadow, then may enter a bounded canary. Aggregate health gates exclude person content and can automatically restore the retained prior version. Hardware qualification records can publish a supported combination only after complete physical-device latency, energy, thermal, offline, update, rollback, semantic-quality, and safe-fallback evidence. The current semantic-experience evidence is synthetic, so its supported matrix is empty.

Common configuration knobs:

Model Packs

Model-pack tooling provides a development and evaluation path for installing weights offline or from a configured source. Model packs are not yet part of a supported appliance release.

Prompt Engine and System Prompt Injection

UnisonOS separates the model from the assistant identity. The model is treated as stateless: UnisonOS compiles and injects the active system prompt at runtime.

See Default System Prompt (Canonical) for the base prompt text.