Kyle Isom
75f5327364
Documents all CLI tools, their projects, install targets, and Nix flake status. Covers server-only binaries, installation via mcpkg.nix, and flake conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# Metacircular Platform Tooling
|
|
|
|
CLI tools for interacting with the Metacircular platform. All tools are
|
|
Go binaries built with `CGO_ENABLED=0` and installed via Nix flakes.
|
|
|
|
## Tool Inventory
|
|
|
|
| Tool | Project | Purpose | Install target |
|
|
|------|---------|---------|---------------|
|
|
| `mcp` | mcp | Control plane CLI — deploy, status, lifecycle, file transfer | vade, orion |
|
|
| `mcp-agent` | mcp | Control plane agent — per-node container management daemon | rift (systemd) |
|
|
| `mciasctl` | mcias | MCIAS admin CLI — accounts, tokens, policies | vade, orion, rift |
|
|
| `mciasgrpcctl` | mcias | MCIAS gRPC debug CLI | vade, orion, rift |
|
|
| `mcproxyctl` | mc-proxy | MC-Proxy admin CLI — routes, firewall, status | vade, orion, rift |
|
|
| `mcrctl` | mcr | MCR admin CLI — repositories, policies, audit | vade, orion, rift |
|
|
| `mcdeploy` | mcdeploy | Deployment CLI — build, push, deploy (bridge tool) | vade |
|
|
|
|
### Server-only binaries (not installed as tools)
|
|
|
|
These run inside containers and are not installed on operator workstations:
|
|
|
|
| Binary | Project | Purpose |
|
|
|--------|---------|---------|
|
|
| `mciassrv` | mcias | MCIAS server |
|
|
| `metacrypt` | metacrypt | Metacrypt server (includes init, unseal, status, snapshot subcommands) |
|
|
| `metacrypt-web` | metacrypt | Metacrypt web UI server |
|
|
| `mcrsrv` | mcr | MCR API server |
|
|
| `mcr-web` | mcr | MCR web UI server |
|
|
| `mc-proxy` | mc-proxy | TLS proxy server |
|
|
| `mcns` | mcns | DNS server |
|
|
| `mcat` | mcat | Login policy tester web app |
|
|
|
|
## Installation
|
|
|
|
All tools are packaged as Nix flakes and installed as system packages
|
|
via `mcpkg.nix` in the NixOS configuration. Adding a tool:
|
|
|
|
1. Create or update `flake.nix` in the project repo.
|
|
2. Add the flake as an input in `/home/kyle/src/nixos/flake.nix`.
|
|
3. Add the package to `configs/mcpkg.nix`.
|
|
4. `sudo nixos-rebuild switch` on target machines.
|
|
|
|
### Nix flake conventions
|
|
|
|
- Channel: `nixos-25.11` (match the system nixpkgs).
|
|
- Build: `pkgs.buildGoModule` with `vendorHash = null` (vendored deps).
|
|
- ldflags: `-s -w -X main.version=${version}`.
|
|
- `subPackages`: list only the client binaries, not servers.
|
|
- `system`: `x86_64-linux` (all machines are x86_64).
|
|
|
|
### MCP agent
|
|
|
|
The `mcp-agent` is a special case: it runs as a systemd service on
|
|
managed nodes (not as a container, since it manages containers). Its
|
|
flake exposes both `mcp` (client) and `mcp-agent` (server). The NixOS
|
|
config in `configs/mcp.nix` references the Nix package path for the
|
|
agent binary.
|
|
|
|
## Flake status
|
|
|
|
| Project | flake.nix | Packages | In mcpkg.nix | Notes |
|
|
|---------|-----------|----------|-------------|-------|
|
|
| mcias | Yes | mciasctl, mciasgrpcctl | Yes | |
|
|
| mc-proxy | Yes | mcproxyctl | Yes | |
|
|
| mcr | Yes | mcrctl | Yes | |
|
|
| mcdeploy | Yes | mcdeploy | Yes | |
|
|
| mcp | Yes | mcp, mcp-agent | Yes | Agent also used by mcp.nix systemd unit |
|
|
| mcns | No | — | No | Server-only, no client tool yet |
|
|
| metacrypt | No | — | No | Server-only, no client tool yet |
|
|
| mcat | No | — | No | Server-only, no client tool yet |
|
|
| mcdsl | No | — | No | Library, no binaries |
|