Kyle Isom
9d543998dc
Recreates containers from the agent's SQLite registry when podman's database is lost (UID change, podman reset, reboot). For each service with desired_state="running" that doesn't have a running container: - Removes any stale container with the same name - Recreates the container from the stored spec (image, ports, volumes, cmd, network, user, restart policy) - Allocates route ports and injects PORT env vars - Re-registers mc-proxy routes - Provisions TLS certs for L7 routes Does NOT pull images — assumes local cache. Root cause action item from the 2026-04-03 UID incident. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
MCP — Metacircular Control Plane
MCP is the orchestrator for the Metacircular platform. It manages container lifecycle, tracks what services run where, and transfers files between the operator's workstation and managed nodes.
Architecture
CLI (mcp) — thin client on the operator's workstation. Reads local
service definition files, pushes intent to agents, queries status.
Agent (mcp-agent) — per-node daemon. Manages containers via rootless
podman, stores a SQLite registry of desired/observed state, monitors for
drift, and alerts the operator.
Quick Start
Build
make all # vet, lint, test, build
make mcp # CLI only
make mcp-agent # agent only
Install the CLI
cp mcp ~/.local/bin/
mkdir -p ~/.config/mcp/services
Create ~/.config/mcp/mcp.toml:
[services]
dir = "/home/<user>/.config/mcp/services"
[mcias]
server_url = "https://mcias.metacircular.net:8443"
service_name = "mcp"
[auth]
token_path = "/home/<user>/.config/mcp/token"
[[nodes]]
name = "rift"
address = "100.95.252.120:9444"
Authenticate
mcp login
Check status
mcp status # full picture: services, drift, events
mcp ps # live container check with uptime
mcp list # quick registry query
Deploy a service
Write a service definition in ~/.config/mcp/services/<name>.toml:
name = "myservice"
node = "rift"
active = true
[[components]]
name = "api"
image = "mcr.svc.mcp.metacircular.net:8443/myservice:v1.0.0"
network = "mcpnet"
user = "0:0"
restart = "unless-stopped"
ports = ["127.0.0.1:8443:8443"]
volumes = ["/srv/myservice:/srv/myservice"]
cmd = ["server", "--config", "/srv/myservice/myservice.toml"]
Then deploy:
mcp deploy myservice
Commands
| Command | Description |
|---|---|
mcp login |
Authenticate to MCIAS |
mcp deploy <service>[/<component>] |
Deploy from service definition |
mcp stop <service> |
Stop all components |
mcp start <service> |
Start all components |
mcp restart <service> |
Restart all components |
mcp list |
List services (registry) |
mcp ps |
Live container check |
mcp status [service] |
Full status with drift and events |
mcp sync |
Push all service definitions |
mcp adopt <service> |
Adopt running containers |
mcp service show <service> |
Print spec from agent |
mcp service edit <service> |
Edit definition in $EDITOR |
mcp service export <service> |
Export agent spec to file |
mcp push <file> <service> [path] |
Push file to node |
mcp pull <service> <path> [file] |
Pull file from node |
mcp node list |
List nodes |
mcp node add <name> <addr> |
Add a node |
mcp node remove <name> |
Remove a node |
Documentation
- ARCHITECTURE.md — design specification
- RUNBOOK.md — operational procedures
- PROJECT_PLAN_V1.md — implementation plan
- PROGRESS_V1.md — progress and remaining work