memql-cockpit

README

MemQL Cockpit

The fleet worker runtime and cluster CLI for MemQL.
Installed as the memql command on the machines you enroll in your fleet.

_{Designed and built with Claude as co-author.}

Status: Alpha / pre-1.0 — not production-ready. MemQL Cockpit is under active development and tracks MemQL core. The worker contract and configuration are still evolving; expect breaking changes between releases.

---

What is MemQL Cockpit?

MemQL Cockpit turns a machine you own into a worker in your MemQL fleet: agents on the cluster can dispatch shell / filesystem / HTTP work to it (headless), and — on the opt-in computer-use build — drive its mouse, keyboard and screen. Machines are managed from the MemQL Portal's Fleet section: pairing, labels, routing policy, activity.

The installed command is memql:

• Enroll a machine — memql cluster add <domain> registers the cluster (identity discovery + OAuth sign-in; RFC 8628 device flow on headless / SSH boxes) and memql worker pair <code> redeems a pairing code from the portal.
• Run as a service — a per-user LaunchAgent on macOS (com.znasllc.memql-worker) or user-systemd unit on Linux (memql-worker.service), auto-started at login.
• Two build variants, one command — headless (default, CGO-free) ships from releases; computer-use (-tags computeruse, CGO + RobotGo) is built per-host. memql --version names the variant.

It communicates with MemQL clusters over gRPC (MemqlService.Stream and WorkerService.Stream) and does not embed the MemQL engine.

Note: the MemQL engine repo also builds a binary named memql, but it ships only inside container images and runs in pods. This CLI is what gets installed on operator machines — different channels, no PATH overlap.

Install

# one-liner (detects OS/arch, checksum-verified)
curl -fsSL https://raw.githubusercontent.com/znasllc-io/memql-cockpit/main/install.sh | sh

# pin a version, or an install dir
curl -fsSL https://raw.githubusercontent.com/znasllc-io/memql-cockpit/main/install.sh | MEMQL_COCKPIT_VERSION=v0.10.0 sh
curl -fsSL https://raw.githubusercontent.com/znasllc-io/memql-cockpit/main/install.sh | BIN_DIR=/usr/local/bin sh

Or, with Go (builds from source):

go install github.com/znasllc-io/memql-cockpit/cmd/memql@latest

Worker-machine installers (binary + service + worker.yaml in one step) live in scripts/install/ — the MemQL Portal's Fleet page composes the exact one-liner for you when you add a machine.

Commands

memql cluster add <domain|url>    Register a cluster (discovery + OAuth login)
memql cluster list | remove       Manage saved clusters
memql login | logout <cluster>    (Re-)authenticate / drop credentials
memql creds <subcommand>          Inspect / migrate the credential store
memql worker pair <code>          Redeem a pairing code, write worker.yaml, run
memql worker run                  Run the worker (what the service invokes)
memql worker setup                Computer-use permission pre-flight (TCC / X11)
memql worker config | consent     Show config / manage consent
memql lint [path]                 Validate a .memql file or DSL tree
memql setup project [flags]       Stamp a new product workspace from the template
memql --version                   Version + build variant

memql worker setup --non-interactive reports missing permissions with honest exit codes and never prompts — for scripted installs.

Build

make cockpit             # headless -> bin/memql
make cockpit-computeruse # computer-use variant -> bin/memql-computeruse
                         #   (CGO; macOS Xcode CLT / Linux libxtst-dev etc.)
make test                # go test ./...  (single module -- this really is everything)
make dist                # versioned tar.gz archives + SHA256SUMS into dist/

The engine is consumed as a pinned sibling checkout — read the memql-pin section in CLAUDE.md before touching go.mod.

Computer-use setup and permissions: docs/computer-use.md.

License

MIT