Kyle Isom
ea8a42a696
- docs/bootstrap.md: step-by-step bootstrap procedure with lessons learned from the first deployment (NixOS sandbox issues, podman rootless setup, container naming, MCR auth workaround) - README.md: quick-start guide, command reference, doc links - RUNBOOK.md: operational procedures for operators (health checks, common operations, unsealing metacrypt, cert renewal, incident response, disaster recovery, file locations) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
120 lines
3.0 KiB
Markdown
120 lines
3.0 KiB
Markdown
# MCP — Metacircular Control Plane
|
|
|
|
MCP is the orchestrator for the [Metacircular](https://metacircular.net)
|
|
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
|
|
|
|
```bash
|
|
make all # vet, lint, test, build
|
|
make mcp # CLI only
|
|
make mcp-agent # agent only
|
|
```
|
|
|
|
### Install the CLI
|
|
|
|
```bash
|
|
cp mcp ~/.local/bin/
|
|
mkdir -p ~/.config/mcp/services
|
|
```
|
|
|
|
Create `~/.config/mcp/mcp.toml`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
mcp login
|
|
```
|
|
|
|
### Check status
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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](ARCHITECTURE.md) — design specification
|
|
- [RUNBOOK.md](RUNBOOK.md) — operational procedures
|
|
- [PROJECT_PLAN_V1.md](PROJECT_PLAN_V1.md) — implementation plan
|
|
- [PROGRESS_V1.md](PROGRESS_V1.md) — progress and remaining work
|