Pnyon

Connect a worker

This is the path from nothing to a running BYO worker serving real embeddings into your Outpost. It's a short loop between you (the adopter, running the worker) and your steward (the person who administers your Outpost and grants access).

Every secret below is a placeholder. Swap <your-outpost-id> for your Outpost's id and <runner-token> for the token your steward hands back — and never paste a real token into a shared channel.

Before you start

  • Access to an Outpost, and a steward you can reach over a trusted channel.
  • A machine you control to run the worker on (this is your compute — it stays with you).
  • The pnyon CLI installed. The install channel ships with your Outpost onboarding; confirm it's on your PATH:
pnyon --version

1. Emit a registration request

The first run of pnyon worker connect does not dial anything. With no worker token in the environment, the CLI generates and stores an ed25519 keypair under ~/.pnyon/ (the private key is written 0600 and never printed), writes ~/.pnyon/config.json, prints a registration request, and exits:

pnyon worker connect \
  --outpost <your-outpost-id> \
  --url wss://dispatch.pnyon.com \
  --display-name my-worker \
  --model onnx-community/Qwen3-Embedding-0.6B-ONNX

It prints a JSON registration request — a public key, a signed binary digest, and your Outpost id and display name as metadata. Only the public key and digest are signed; the Outpost id and name are unsigned, which is why your steward verifies your identity out-of-band before trusting you.

2. Hand the request to your steward

Send the registration request to your steward over a trusted channel. They:

  • confirm out-of-band that you really operate <your-outpost-id>,
  • trust your worker's public key,
  • and mint you a runner token scoped to that Outpost.

The token is shown once. Your steward passes it back to you — treat it like a password.

3. Connect and serve

Re-run pnyon worker connect with the token in the environment. This time the CLI reads the private key from ~/.pnyon/ (never from the environment), dials wss://dispatch.pnyon.com/outpost/<your-outpost-id>, registers with a fresh attestation, and starts serving embed work. The url, model, and display name are read back from ~/.pnyon/config.json, so you only pass the Outpost:

PNYON_WORKER_TOKEN='<runner-token>' \
pnyon worker connect --outpost <your-outpost-id>

connect is the embedder: it loads the model it advertises and serves real vectors — it never advertises a model while returning stub data. You don't set any executor override for normal use.

4. Verify with pnyon doctor

pnyon doctor runs each prerequisite fail-closed and finishes with a bounded probe against your Outpost's dispatch endpoint. It reports a clear PASS, an actionable FAIL, or a benign SKIP for each check, and exits non-zero if any gate would reject you:

PNYON_WORKER_TOKEN='<runner-token>' pnyon doctor

The checks cover your config and keypair, a well-formed token, a configured model, and an online probe that distinguishes the interesting failures: your key isn't trusted yet (share your request again), the token is invalid or expired (ask for a re-mint), or the dispatch endpoint is unreachable. A successful probe proves your token and attestation were accepted — it does not prove leasing eligibility, which is checked later when work is actually pulled.

What "connected" means

Once connect is serving and doctor is green, your worker is dialed into wss://dispatch.pnyon.com/outpost/<your-outpost-id> and answering embed requests with real vectors from the model you advertised. A comprehension request in your Outpost now routes to your machine and comes back with a real embedding.

The submit path is a second gate: a request carrying a missing or wrong submit token fail-closes with a 401 before any embed work happens. Nothing in this flow ever returns a fabricated vector — a bad token, an untrusted key, or a failed invariant is rejected, not faked.

Next

Read Outposts & the BYO worker model for why the handshake is shaped this way, and run pnyon worker connect --help / pnyon doctor --help for the full set of flags.