98b166fa7b
A unikernel VM has no runtime restart policy, so if it exits — including when an agent restart's cgroup kill takes it down — nothing restarts it, and it sits in drift. Recover() already handles this (and unikernels, via runtimeFor), but only ran inside RunBootSequence, which is gated on a [boot] sequence that worker nodes don't define. Now the agent also runs Recover once in the background on startup when there is no boot sequence, so desired=running components (VMs especially) come back after an agent or host restart without delaying registration. Co-Authored-By: Claude Opus 4.8 <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