How arttribute/common-os works
1. Monorepo layout
- This is a TypeScript pnpm workspace with three product surfaces in apps/ and five shared packages in packages/.
- The architectural split is clear: control plane API, operator UI, agent runtime/daemon, and reusable SDK/CLI/cloud abstractions.
2. Control plane API (apps/api)
- The API is the system’s backend hub. It exposes fleet, agent, task, event, wallet, session, and auth routes.
- It is a Hono-based Node service that persists domain state in MongoDB via Mongoose models under src/db/models.
- The API is also the event ingestion point for agents and the broadcast source for the live world stream.
3. Domain state and persistence
- Mongo collections model the core objects: tenants, fleets, agents, sessions, tasks, messages, events, world state, wallets, and human messages.
- memory.ts suggests a non-persistent or demo/in-memory implementation used for local or fallback behavior.
- World state is not just computed client-side; it is stored and served from the API as a snapshot that the UI can reconcile against.
4. Authentication and identity
- The repo supports Privy-backed tenant auth plus two token classes: tenant API keys and agent-scoped tokens.
- Human operators use tenant credentials to manage fleets; agents use injected tokens to call daemon-only and event routes.
- This creates a hard boundary between fleet administration and agent runtime capabilities.
5. Fleet and agent lifecycle
- Fleet creation, agent deployment, updates, and termination all flow through the API.
- Provisioning is handled by services in apps/api/src/services, with cloud-specific logic abstracted behind provider code and a runner service.
- The agent deploy path is the main infrastructure control loop: API request → provisioning service → cloud runtime/pod creation → agent bootstraps back into the control plane.
6. Agent runtime inside pods
- apps/runner is a Cloud Run service that wraps agent-commons execution.
- apps/api/agent contains the container image and entrypoint used for agent pods.
- packages/daemon is the process that runs inside each agent pod, handling task polling, heartbeats, health monitoring, file watching, and event emission back to the API.
7. P2P communication path
- The system integrates Gensyn AXL as a direct agent-to-agent messaging layer.
- Each pod runs an AXL node, registers its multiaddr with the control plane, and exchanges messages peer-to-peer rather than through a central broker.
- The API persists message history and peer metadata, but the actual transport is decentralized.
8. World simulation and live UI (apps/web)
- The web app is a Next.js 15 frontend that combines a React HUD with a Phaser-based isometric world.
- WorldScene, UIScene, and the HUD components render agents, movement, objects, and task state as a spatial simulation.
- Zustand stores and useWorldConnection subscribe to the API’s WebSocket stream and keep the simulation in sync with server events.
9. Event-driven data flow
- Agents emit events to POST /events, the API stores them and rebroadcasts them over WebSocket, and the UI consumes them in real time.
- This is the primary cross-cutting flow for task lifecycle, movement, state changes, file changes, and messages.
- The same event stream powers both the visual world and the operational dashboards.
10. Client tooling (packages/cli and packages/sdk)
- @common-os/cli provides the cos command for operators: auth, fleet management, agent deployment, task submission, logs, and world inspection.
- @common-os/sdk provides typed clients for both human operators and in-pod agents, so the same control plane can be used from UI, CLI, and runtime code.
- These packages are thin client boundaries over the API rather than separate services.
11. Cloud/provider abstraction
- @common-os/cloud contains AWS and GCP provider implementations, indicating the platform is designed to launch agent workloads across cloud backends.
- Deployment assets and CI/CD are split by component with Dockerfiles, Cloud Build configs, and GitHub Actions workflows.
- The repo is therefore not just an app; it is a deployment platform with infrastructure orchestration, runtime packaging, and a real-time operator experience.
12. Important product boundary
- The architecture intentionally separates “control plane” concerns from “embodied simulation” concerns.
- The API and runtime packages own truth, permissions, and provisioning; the web app is a projection of that truth into a spatial interface.
- That separation is what makes the system diagrammatic: operations happen in the backend, but their consequences are visualized live in the world UI.
Main entry points: events.ts Event Ingest · fleets.ts Routes · provisioner.ts Provisioner · WorldClient.tsx World Client
Components 22
Control Plane
Backend API, persistence, provisioning, and agent runtime image.
- API Server · Main control-plane entrypoint mounting auth, fleet, agent, task, message, wallet, session, event, and stream routes.
apps/api/src/index.ts - Auth · Tenant authentication and token resolution boundary for operator and agent requests.
apps/api/src/middleware/auth.ts - Routes · Primary route layer for auth, fleets, agents, tasks, sessions, messages, wallets, events, stream, and agent runtime.
apps/api/src/routes/fleets.ts - Event Ingest · Stores agent events and rebroadcasts them to live consumers.
apps/api/src/routes/events.ts - World Stream · Broadcast channel for world state and operational updates consumed by the UI.
apps/api/src/routes/stream.ts - Mongo DB · Mongo connection and data access layer for control-plane state.
apps/api/src/db/mongo.ts - Domain Models · Collections for tenants, fleets, agents, sessions, tasks, messages, events, wallets, and world state.
apps/api/src/db/models/index.ts - World State · Maintains the server-side world snapshot served to the UI.
apps/api/src/services/world.ts - Provisioner · Orchestrates fleet creation, agent deployment, and cloud runtime startup.
apps/api/src/services/provisioner.ts - Cloud Init · Builds agent startup configuration and runtime bootstrap payloads.
apps/api/src/services/cloud-init.ts
Operator UI
Next.js frontend and live world simulation.
- World Page · Primary world surface combining HUD and isometric simulation.
apps/web/app/world/page.tsx - World Client · Connects the UI to the control plane and live world stream.
apps/web/components/WorldClient.tsx - World Scene · Renders agents, objects, movement, and task state in the spatial simulation.
apps/web/game/scenes/WorldScene.ts - World Sync · Subscribes to the API websocket and keeps local stores in sync.
apps/web/hooks/useWorldConnection.ts - World Store · Client-side state for agents, world entities, and live updates.
apps/web/store/worldStore.ts
Runtime
Agent pod process, runner wrapper, and entrypoint.
- Runner · Cloud Run wrapper for agent-commons execution.
apps/runner/src/index.ts - Agent Image · Container image and entrypoint used to launch agent pods.
apps/api/agent/entrypoint.sh - Daemon · Runs inside each agent pod to poll tasks, send heartbeats, watch files, and emit events.
packages/daemon/src/daemon.ts
Shared Packages
Reusable CLI, SDK, cloud, and schema libraries.
- CLI · Command-line surface for auth, fleet management, agent deployment, tasks, logs, and inspection.
packages/cli/src/cli.ts - SDK · Shared client library for operator and in-pod access to the control plane.
packages/sdk/src/index.ts - Cloud Abstraction · AWS and GCP provider implementations behind fleet deployment.
packages/cloud/src/factory.ts - Event Schema · Shared event definitions for the control plane and runtime.
packages/event-schema/src/index.ts
Connections 25
- API Server → Auth: uses · All control-plane requests pass through auth boundary.
- API Server → Routes: mounts · Server wires the domain route modules.
- Routes → Mongo DB: reads/writes · Route handlers persist and query state.
- Mongo DB → Domain Models: uses · Mongo collections are defined through models.
- Routes → Event Ingest: ingests · Agent events enter the control plane here.
- Event Ingest → World Stream: rebroadcasts · Stored events are pushed to live subscribers.
- Event Ingest → World State: updates · Event ingestion reconciles the server-side world snapshot.
- Provisioner → Cloud Init: builds · Provisioning prepares runtime bootstrap data.
- Provisioner → Cloud Abstraction: delegates · Cloud-specific launch logic is abstracted behind provider implementations.
- Provisioner → Runner: starts · Agent workloads are launched through the runner path.
- Provisioner → Agent Image: boots · Agent pods use the packaged container entrypoint.
- Runner → Daemon: executes · Runner wraps agent-commons execution for the pod.
- Daemon → Event Ingest: emits · Daemon sends task, heartbeat, health, and file events upstream.
- Daemon → SDK: uses · Runtime relies on typed control-plane client behavior.
- CLI → SDK: wraps · CLI is a thin operator surface over the SDK.
- SDK → Routes: calls · SDK targets the control-plane HTTP API.
- World Page → World Client: contains · World page composes the live client bridge.
- World Client → World Sync: subscribes · Client bridge listens to live control-plane updates.
- World Sync → World Stream: connects · UI syncs through the websocket world stream.
- World Client → World Scene: drives · Incoming events update the Phaser world.
- World Scene → World Store: reads/writes · Scene state is mirrored in client stores.
- World Client → Routes: queries · UI also uses control-plane endpoints for current state and actions.
- SDK → Event Ingest: posts · Agent and operator clients can submit events through the shared API surface.
- Event Schema → Event Ingest: defines · Shared schema keeps event payloads aligned.
- Event Schema → Daemon: defines · Runtime event payloads follow shared contracts.