Workspace and Repositories¶

Unison uses a multi-repo layout under the project-unisonOS organization, with a recommended workspace for local development.

Workspace Layout¶

The workspace typically contains these repos side-by-side:

• Core control plane services (orchestrator, policy, consent, auth, inference, intent-graph, context-graph).
• Context and storage services.
• Experience and IO services (renderer, shell, agent-vdi, io-core, io-speech, io-vision).
• Devstack, shared docs, common library, base OS images, and optional services such as payments.

See the internal repository map in unison-docs/dev/unison-repo-map.md for a detailed table.

Recommended: Meta-Repo Workflow¶

The meta-repo workflow provides a single entry point:

• Clone the workspace that brings the core repos in as submodules.
• Use workspace scripts to:
• Initialize submodules.
• Start the devstack.
• Run end-to-end smoke tests.

In the current workspace (unison-workspace):

• ./scripts/bootstrap.sh: initializes and updates all submodules.
• ./scripts/up.sh: brings up the devstack (uses unison-devstack/docker-compose.yml plus unison-devstack/docker-compose.ports.yml).
• ./scripts/up-security.sh: brings up devstack with the security overlay (unison-devstack/docker-compose.security.yml) and no host port publishing.
• ./scripts/smoke.sh: runs the devstack end-to-end smoke test (HTTP health checks and a basic voice/vision flow).
• ./scripts/smoke-security.sh: runs the smoke test inside the Docker network and asserts ports are not published in security overlay mode.

This keeps versions aligned and makes it easy to run the full stack locally.

Alternative: Side-by-Side Clones¶

Alternatively, you can clone the individual repos side-by-side under a common parent directory:

• Clone the devstack repo and the core services you intend to work on.
• Keep a shared constraints.txt at the workspace root and point Python services to it.
• For each Python service, create a virtual environment, install dependencies, and copy or create .env files.

Use the approach that best fits your workflow; both are supported by the documentation and tools in the workspace.

Repository Directory (links to repo + README)¶

Below is the current workspace directory with direct links to each repo and its README for deep dives.

• unison-workspace: meta repo with submodules and helper scripts (unison-workspace README)
• unison-devstack: Docker Compose for local edge-first stack (unison-devstack README)
• unison-orchestrator: central intent orchestrator + companion manager (unison-orchestrator README)
• unison-context: encrypted profiles + dashboard state (unison-context README)
• unison-context-graph: context traces/recall graph (unison-context-graph README)
• unison-intent-graph: intent routing/cache (unison-intent-graph README)
• unison-experience-renderer: Operating Surface UI (dashboard, shared space) (unison-experience-renderer README)
• unison-io-core: generic IO ingress/egress (unison-io-core README)
• unison-io-speech: speech IO (STT/TTS) (unison-io-speech README)
• unison-io-vision: vision capture/describe (unison-io-vision README)
• unison-io-sign: sign language I/O services (detector, interpreter, providers, avatar adapter) (unison-io-sign README)
• unison-io-bci: BCI ingest/decoder service (LSL/BLE/serial stubs, decoders, HID, raw snapshots, export) (unison-io-bci README)
• unison-io-braille: Braille IO service (device discovery, translators, HID/BT drivers, focus feed, profiles) (unison-io-braille README)
• unison-sign-orchestrator: sign modality gateway (intent mapping and response routing) (unison-sign-orchestrator README)
• unison-actuation: deterministic actuation gateway (Action Envelope validation, policy/consent, driver routing) (unison-actuation README)
• unison-auth: auth service (unison-auth README)
• unison-consent: consent service (unison-consent README)
• unison-policy: policy enforcement service (unison-policy README)
• unison-storage: durable KV/files (unison-storage README)
• unison-inference: inference gateway (local-first) (unison-inference README)
• unison-common: shared Python library (unison-common README)
• unison-payments: optional payments service (unison-payments README)
• unison-agent-vdi: VDI agent / renderer proxy (unison-agent-vdi README)
• unison-network-vpn: VPN sidecar for VDI/actuation egress (unison-network-vpn README)
• unison-os: base OS image definitions (unison-os README)
• unison-platform: deployment/config/meta platform assets (unison-platform README)
• unison-comms: communications service (email/unison channels) (unison-comms README)
• unison-docs: internal docs and design notes (unison-docs README)
• project-unisonos.github.io: public docs site (project-unisonos.github.io README)

(If a repo is missing from this list, add it here and ensure its README links to the public docs.)