From 75f532736456745a0a8630f26c71447d7e9d0471 Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Thu, 26 Mar 2026 22:48:48 -0700 Subject: [PATCH] Add TOOLING.md: platform CLI tools and Nix packaging reference 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) --- TOOLING.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 TOOLING.md diff --git a/TOOLING.md b/TOOLING.md new file mode 100644 index 0000000..88b6c36 --- /dev/null +++ b/TOOLING.md @@ -0,0 +1,71 @@ +# 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 |