# openalice-orchestrator

> Multi-instance orchestrator for OpenAlice — manages lifecycle, docker-compose routing, and A2A mesh discovery.

## At a glance
| field | value |
|---|---|
| kind | `infrastructure` |
| priority | `P4` |
| default branch | `mvp` |
| last activity | 2026-05-21T03:02:39+00:00 |
| features catalogued | **15** |
| runtime deps declared | **1** |

## Manifest
`.atlas-deps.yml` — parsed cleanly: **yes**

### Runtime deps
- **`openalice`** · `other` · via `docker compose / container volume mount` — Spawns and manages openalice containers; mounts alice binary + entrypoint from the main repo build.

### Consumed env
- `ORCH_PORT`
- `ORCH_BASE_PORT`
- `HOME`

### Exposes
- `http_endpoint` — http://orchestrator:8200/api/v1/*

## Env drift

**Manifest declares, code unused (1):**
- `HOME`

## Features (15)

### orchestrator/a2a
- **`orchestrator.api.mesh-status`** · _alpha_ · since 0.1.0 — Polls every running instance's `/.well-known/agent.json`, returns aggregated A2A mesh view with agent cards.  
  *src/main.rs:1001*

### orchestrator/api
- **`orchestrator.api.create-instance`** · _alpha_ · since 0.1.0 — Allocates id+port, validates+slugs name, writes alice.yaml and compose file, persists registry.  
  *src/main.rs:506*
- **`orchestrator.api.get-instance`** · _alpha_ · since 0.1.0 — Fetches a single instance by UUID, 404 if absent.  
  *src/main.rs:655*
- **`orchestrator.api.health`** · _alpha_ · since 0.1.0 — Reports orchestrator status, version, total + running instance counts, and uptime.  
  *src/main.rs:482*
- **`orchestrator.api.instance-health-proxy`** · _alpha_ · since 0.1.0 — Probes `http://{container}:8080/health` via Docker DNS; reports reachability + latency.  
  *src/main.rs:945*
- **`orchestrator.api.list-instances`** · _alpha_ · since 0.1.0 — Returns redacted views (tokens stripped) of every registered instance.  
  *src/main.rs:641*

### orchestrator/config
- **`orchestrator.bin.openalice-orchestrator`** · _alpha_ · since 0.1.0 — Reads ORCH_PORT (listen, default 8200) and ORCH_BASE_PORT (instance port base, default 8080) from env.  
  *src/main.rs:13*

### orchestrator/lifecycle
- **`orchestrator.lifecycle.delete-instance`** · _alpha_ · since 0.1.0 — Tears down compose stack, removes compose file, drops registry entry; preserves data dir on disk.  
  *src/main.rs:875*
- **`orchestrator.lifecycle.port-allocator`** · _alpha_ · since 0.1.0 — Allocates the next free TCP port for a new instance by incrementing the current max.  
  *src/main.rs:268*
- **`orchestrator.lifecycle.start-instance`** · _alpha_ · since 0.1.0 — Shells out to `docker compose up -d --build` against the instance's compose file; transitions Created→Starting→Running.  
  *src/main.rs:680*
- **`orchestrator.lifecycle.stop-instance`** · _alpha_ · since 0.1.0 — Runs `docker compose down`; marks Stopped even on partial failure so registry stays consistent.  
  *src/main.rs:795*

### orchestrator/persistence
- **`orchestrator.persistence.instance-files`** · _alpha_ · since 0.1.0 — Materializes the instance's data dir, alice.yaml, and compose file under the orchestrator data dir.  
  *src/main.rs:600*

### orchestrator/template
- **`orchestrator.template.alice-yaml`** · _alpha_ · since 0.1.0 — Emits a fully-formed alice.yaml (router tiers, connectors, browser, rank) per spawned instance.  
  *src/main.rs:289*
- **`orchestrator.template.docker-compose`** · _alpha_ · since 0.1.0 — Renders per-instance docker-compose with Traefik labels, healthcheck, resource limits, and openalice/proxy networks.  
  *src/main.rs:376*

### orchestrator/util
- **`orchestrator.util.slug`** · _alpha_ · since 0.1.0 — Normalizes instance names into Traefik/Docker-safe slugs (lowercase, alphanumeric + dashes).  
  *src/main.rs:462*

---

*Generated by [openalice-atlas](https://atlas.blal.pro) — single source of truth for the openalicelabs ecosystem.*