Oslo

Oslo is a lightweight interoperability layer for AI agents, LLMs, tools, scripts, and external APIs. It gives them a shared JSON envelope, task lifecycle semantics, capability registration, and traceable execution without forcing a heavyweight distributed platform on day one.

Oslo sits between orchestration and execution:

• agents register capabilities
• callers submit typed tasks
• runtimes emit progress, results, errors, approvals, and artifacts
• operators inspect traces, task state, and system health

The long-term goal is a simple control plane for interoperable agent systems that can grow into self-hosted or managed SaaS. The current repo is an MVP foundation, not a finished platform.

• packages/protocol: real versioned envelope schemas, event taxonomy, and validation
• apps/control-plane: real Fastify API with persistence in Postgres
• packages/sdk: real typed client for agent registration and task lifecycle calls
• packages/agent-runtime: real runtime abstraction for capability handlers
• apps/runtime-gateway: real HTTP ingress for a mock agent runtime
• Docker Compose stack for local Postgres + control-plane + runtime-gateway
• lint, typecheck, tests, integration test, build, and GitHub Actions

• apps/runtime-gateway currently runs a single mock/local agent and should be read as an adapter seam, not as a production-ready execution fabric
• apps/dashboard is intentionally placeholder UI and is not on the critical MVP path
• auth is development-grade API key auth only
• approvals exist in the model and API, but the happy path is still task execution rather than approval workflows

• apps/control-plane: source of truth for agents, tasks, task events, approvals, artifacts, metrics, and health
• apps/runtime-gateway: thin runtime-facing boundary used by the demo path
• packages/protocol: Oslo envelope, task statuses, capability declarations, and zod validation
• packages/sdk: typed HTTP client for callers and runtimes
• packages/agent-runtime: capability handler runtime with progress/result reporting
• packages/shared: config, auth helpers, IDs, logging, and HTTP helpers
• apps/dashboard: placeholder operator UI

Control plane and runtime gateway are the critical MVP path. Dashboard is not.

• apps/control-plane
• apps/runtime-gateway
• apps/dashboard
• packages/protocol
• packages/sdk
• packages/agent-runtime
• packages/shared
• infra/compose
• infra/docker
• docs
• .github

Ports are centralized in .env.example and should be copied into .env for local work.

Default values:

• OSLO_CONTROL_PLANE_PORT=4310
• OSLO_RUNTIME_GATEWAY_PORT=4311
• OSLO_DASHBOARD_PORT=4312
• OSLO_POSTGRES_PORT=55432

Run pnpm preflight before local startup. It detects occupied ports and suggests alternative values to put in .env.

1. Copy .env.example to .env.
2. Run pnpm install.
3. Run pnpm preflight.
4. Start the Docker stack with pnpm docker:up.
5. Check health with pnpm status.
6. Run the host demo against Docker with pnpm demo:docker.

If you want to run the apps directly on the host instead of Docker:

1. Ensure Postgres is available at DATABASE_URL.
2. Run pnpm db:migrate.
3. Run pnpm db:seed.
4. Run pnpm dev.
5. In another terminal run pnpm demo.

There are two demo paths:

• pnpm demo
  • Use when control-plane and runtime-gateway are running on the host.
  • Registers the mock agent, sends a task, and prints task state plus event trace.
• pnpm demo:docker
  • Use when the Docker Compose stack is running.
  • Executes the same demo from inside the control-plane container so internal service URLs stay correct.

• pnpm dev: preflight + control-plane + runtime-gateway
• pnpm dev:all: same as dev plus dashboard
• pnpm dev:dashboard: dashboard only
• pnpm build
• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm test:integration
• pnpm preflight
• pnpm status
• pnpm docker:up
• pnpm docker:down
• pnpm demo
• pnpm demo:docker

• PR template: .github/pull_request_template.md
• Issue templates: .github/ISSUE_TEMPLATE
• Copilot guidance: .github/copilot-instructions.md
• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• GitHub backlog bootstrap: docs/github/backlog-bootstrap.md

• Replace the mock runtime with pluggable transports and external agents
• Introduce stronger authn/authz and tenancy boundaries
• Add a real operator dashboard for task/event inspection
• Add MCP, webhook, and provider adapters
• Harden approval workflows and artifact storage

• transport model after HTTP-first MVP
• approval policy representation beyond development stubs
• storage strategy for artifact payloads
• multi-tenant boundaries and billing model
• when to move from a mock gateway to queue-backed delivery

• Keep packages/protocol as the only source of truth for envelope shape and lifecycle names
• Add new adapters behind narrow boundaries instead of leaking provider details into the control plane
• Prefer explicit capability declarations and typed schemas over ad hoc payloads
• Treat apps/runtime-gateway as the adapter seam for HTTP, local handlers, webhooks, MCP, or queue consumers