Meta Proxy (ruflo proxy) — technical tutorial: architecture, install/verify pipeline, data planes, full CLI reference

meta-proxy-tutorial.md

Meta Proxy — a technical tour of ruflo proxy

ruflo ships a local, OpenAI-compatible LLM proxy called Meta Proxy (binary name meta-proxy). This is a walkthrough of what it actually does, how it's built, and how to run it — grounded directly in the shipped CLI source (v3/@claude-flow/cli/src/commands/proxy.ts, proxy-lifecycle.ts, src/proxy/*.ts) and its governing ADRs (ADR-304, ADR-307, ADR-313/314/315) in ruvnet/ruflo.

What it is

Client (any OpenAI-compatible tool)
      │
      ▼
127.0.0.1:11435  ──  meta-proxy (local Rust process)
      │
      ├── local backend (Ollama / vLLM / SGLang) — never leaves the machine
      │
      └── api.cognitum.one — only if you explicitly opt in
             │
             ▼
       Claude / GPT / Gemini / DeepSeek / OpenRouter

One binary, no Node dependency, bound to loopback only (127.0.0.1:11435 by default — never a privileged port). It speaks the OpenAI chat-completions wire format, so anything that already knows how to talk to api.openai.com can point at it instead.

The load-bearing design constraint (ADR-307): "local proxy" means the proxy process is local. It does not imply inference is local. Whether your requests ever leave the machine is a separate, explicit setting — covered below.

Quickstart

ruflo proxy install --yes    # download, verify, install the signed binary
ruflo proxy start            # run in the foreground
ruflo proxy status           # installation + process status
ruflo proxy logs -f          # tail the log
ruflo proxy stop

install resolves your platform's release asset, downloads it from the public distribution channel, verifies it, and drops the binary at ~/.ruflo/bin/meta-proxy. Nothing runs until you call start.

Install internals — what "verified" actually means

ruflo proxy install isn't just a curl | tar. The pipeline (src/proxy/install.ts) is:

1. Fetch the release asset for your platform from github.com/cognitum-one/meta-proxy-dist — 5 published target triples (macOS arm64/x64, Linux x64/arm64-gnu, Windows x64-msvc), named meta-proxy-<version>-<triple>.<tar.gz|zip>.

2. Verify (src/proxy/verify.ts): the release ships one combined SHA256SUMS.sig — a raw Ed25519 signature (base64) over the whole SHA256SUMS file — checked against a pinned public key:

   -----BEGIN PUBLIC KEY-----
   MCowBQYDK2VwAyEAjhLDomjIGdcltYC7j+aiESQFD4LWoHaULietG1PuDjw=
   -----END PUBLIC KEY-----
   

   Then the downloaded archive's own SHA-256 is checked against its entry in SHA256SUMS. Any mismatch throws — there's no partial-trust path.

3. Extract into a throwaway temp dir (fs.mkdtempSync(os.tmpdir() + '/ruflo-proxy-install-')), and validate the extracted binary's path against that same temp dir with PathValidator (defense-in-depth against a symlink swap during extraction).

4. Install atomically — copy to a .tmp path next to the final destination, then renameSync over it — and write ~/.ruflo/proxy/install-manifest.json (version, sha256, verify timestamp, pubkey fingerprint).

The install version is pinned, not "latest" — ruflo proxy install --yes always installs a specific reviewed release (DEFAULT_PROXY_RELEASE in proxy-lifecycle.ts, currently 0.7.3), verified through the same signature/checksum path either way. Pass --release x.y.z to pin a different one yourself.

One deliberate quirk worth knowing if you ever read the source: the per-user bearer token (~/.ruflo/proxy-token, mode 0600) is not generated by the installer — the meta-proxy binary creates it itself on first launch. install.ts carries a comment noting this was confirmed empirically against the real binary, not assumed.

Data planes — where your requests actually go

By default, Meta Proxy is local-only. Cloud routing is an explicit, disclosed opt-in — never a silent fallback:

Plane	Command	What happens
local (default)	ruflo proxy config --local-only	Requests go to your own backend (Ollama/vLLM/SGLang). Never leave the machine.
passthrough	ruflo proxy config --passthrough	Requests go to your own Claude subscription. Meta Proxy's own default when cloud routing is off.
cloud	ruflo proxy config --cloud --yes	Cloud-tier requests go to api.cognitum.one, billed to your own Cognitum account.
sponsored	ruflo proxy sponsor-enable --yes	Requests go through Cognitum's sponsored capacity — free, rate-limited, best-effort, only while your own Claude usage limit has reset.

Notice passthrough and local-only look similar ("cloud routing is off") but are genuinely different destinations — one is your Claude account, the other is your own local model. The CLI keeps them as separate flags on purpose, after an earlier UX pass found people conflating them.

Enabling --cloud also lets you pick how the cloud plane routes:

ruflo proxy config --routing-mode auto   # difficulty-based tier selection (default)
ruflo proxy config --routing-mode high   # pin to the top tier

Consent, not a silent toggle

sponsor-enable and power-saver-enable both print a full disclosure before anything changes, and both require --yes to actually confirm (you can read the disclosure once, un-confirmed, then re-run with --yes):

ruflo proxy sponsor-enable Enabling sponsored downtime mode.

While your Claude usage limit resets, requests can be routed through Cognitum's own model capacity, sponsored at no cost to you. This is a separate data plane from your own cloud-routing config — Cognitum sees these prompts (server-side, same handling as any api.cognitum.one request), never your own Claude account.

Sponsored capacity is rate-limited and best-effort — Cognitum may throttle or decline requests under load. Disable anytime: ruflo proxy sponsor-disable

ruflo proxy power-saver-enable Enabling power saver mode.

Everyday requests will route through Cognitum's own difficulty-based router (cognitum-auto) instead of your Claude subscription directly — simple messages stay cheap, genuinely hard reasoning still escalates to a comparable frontier model. This is billed to YOUR OWN Cognitum account (cloud-routing), not sponsored/free capacity — a separate decision from sponsored downtime mode.

Disable anytime: ruflo proxy power-saver-disable

A third, independent consent (training-share-enable) lets sponsored-plane requests carry an X-Cognitum-Training-Consent: true header — off by default, and orthogonal to the other two.

Full CLI reference

ruflo proxy                                     # status + guidance (no args)
ruflo proxy install [--release x.y.z] [--yes]   # download, verify, install
ruflo proxy update  [--release x.y.z]           # re-verify and replace
ruflo proxy start   [--service]                 # foreground by default
ruflo proxy supervise                           # internal — used by --service
ruflo proxy stop
ruflo proxy status  [--json]
ruflo proxy logs    [-f | --follow]
ruflo proxy uninstall

ruflo proxy config [--cloud] [--local-only] [--passthrough]
                    [--routing-mode auto|low|mid|high] [--yes]

ruflo proxy sponsor-enable|sponsor-disable|sponsor-status|sponsor-clear [--yes]
ruflo proxy power-saver-enable|power-saver-disable|power-saver-status|power-saver-clear [--yes]
ruflo proxy training-share-enable|training-share-disable|training-share-status [--yes]

--service on start detaches the process, writes a PID file, and logs to ~/.ruflo/proxy.log — it "survives closing the terminal, not a reboot." Full OS-service registration (launchd/systemd/user-service) is explicitly deferred per ADR-307; today it's a detached process + PID file, nothing more.

Lifecycle internals

• Start: an O_EXCL lockfile (~/.ruflo/proxy.lock) makes concurrent start calls safe — the second one fails cleanly instead of racing.

• Stop: SIGTERM, wait ~1s, SIGKILL if it's still alive.

• Status: because meta-proxy pre-v0.7.2 starts a live server on any invocation (there's no safe --version/--help flag), ruflo never executes the binary just to check its version. Version comes from the install manifest; a running instance's live status is instead read from its own GET /status endpoint (bearer-authed), and only after a PID-liveness check passes:

  {"version":"0.1.0","data_plane":"passthrough:anthropic","bind":"127.0.0.1:11435","sponsored_available":false,"proxy_token_valid":true}

• Injected-token bridge: ruflo auth login holds your OAuth access token in process memory only. Meta Proxy is a long-running daemon that needs a durable credential, so ruflo actively pushes a fresh token into ~/.ruflo/proxy-injected-token.json every 30 seconds, rather than handing the daemon a refresh token it would have to hold onto itself.

File layout

~/.ruflo/bin/meta-proxy                 the binary
~/.ruflo/proxy-token                    per-user bearer token (0600), created by the binary itself
~/.ruflo/proxy-config.toml              data-plane + routing-mode config
~/.ruflo/proxy/install-manifest.json    version, sha256, verify timestamp, pubkey fingerprint
~/.ruflo/proxy.pid / proxy.lock         lifecycle bookkeeping for --service mode
~/.ruflo/proxy.log                      background-mode log
~/.ruflo/proxy-injected-token.json      ruflo's live OAuth token, pushed every 30s

($RUFLO_STATE_DIR overrides ~/.ruflo if you need a non-default location.)

One thing this is not

ruflo also has an internal, developer-only MCP integration (metallm_ask / metallm_delegate) that lets a Claude Code session delegate sub-tasks through the same underlying Cognitum gateway. It sounds related — "meta" and "proxy/gateway" show up in both — but it's a different system: no public distribution, no versioned API contract, and its source isn't in this repository at all. If you're building against Meta Proxy as a product, the CLI documented above is the whole surface; you don't need — and as an external user, can't reach — the dev-bridge.

Governing ADRs

• ADR-304 — product definition: architecture, data-plane disclosure model, privacy defaults.
• ADR-307 — runtime, packaging, signature verification, service lifecycle.
• ADR-313 / ADR-314 / ADR-315 — sponsored downtime, power saver mode, and the free-user training-data-sharing pipeline, respectively.

One numbering note if you go spelunking in the source: some in-code comments cite ADR numbers like "meta-proxy ADR-321" — that's meta-proxy's own internal ADR series, a different private repo, not ruflo's own v3/docs/adr/. The two numbering spaces overlap by coincidence, not by reference — don't cross-cite them.