Connect a Pylon
Read or copy the Markdown · Live network
A Pylon runs a model on your computer and contributes it to the mesh. Load original Elephant on your GPU, then verify an encrypted relay task with your own Pylon.
Report a bug or request a feature
1. Prepare
Elephant downloads 18.8 GB of original BF16 weights plus about 20 MB of tokenizer data. Reserve 40 GB of free disk for the cached model and build headroom. The 14-minute transfer limit can require several runs on slower links; timed-out downloads retain partial files and the same command resumes them.
Use macOS or Linux with outbound HTTPS and secure WebSockets. No inbound port or public IP is required. Install Git, Python 3, curl and a C/C++ compiler. You do not need Bun, a wallet, an API credential or a paid account to contribute a Pylon.
Mac: the qualified configuration is an Apple M5 Max with 128 GB of unified memory, macOS 26 and Xcode 26.6 with SDK 26.5. This path uses Metal 4 and Metal Performance Primitives; Command Line Tools alone are not the qualified setup. Select your installed Xcode developer directory before running it.
Linux: use an NVIDIA CUDA GPU with its working driver, NVRTC and Nix for the OpenSSL dependency. Native Elephant has run on RTX 4080 16 GB, L4 24 GB and RTX PRO 6000 96 GB; smaller cards can stream selected tensors from host RAM. The recorded CUDA runtime uses driver 595 and NVRTC 13.2.86. Plan at least 32 GB of host RAM, with extra headroom for model mappings, pinned streaming buffers and workspace; GPU VRAM alone is not sufficient. These are qualified configurations, not a promise that every GPU or smaller Mac works.
The installer probes native GPU/toolchain support before downloading. Unsupported setups fail with an explicit toy alternative. It never silently substitutes a toy for Elephant. If you only want the small network smoke test, use the separate toy command below.
2. Load and connect
Download the script, inspect it, then run the learned-model path:
curl -fsSL https://openagents.com/pylon/join.sh -o /tmp/join-pylon.sh
bash /tmp/join-pylon.sh --model elephant-1 --self-test
The script clones or updates OpenAgents, builds checked Coax and its native Metal or CUDA engine, fetches the pinned original checkpoint, creates a private disposable demo identity, and connects to wss://relay.openagents.com. Keep the terminal open. A cold compiler build, model download and first authentication take longer than later starts.
Every model file is authenticated before use. The engine loads the weights onto the native GPU and passes a known-answer doctor before the Pylon advertises available capacity. Failed loading or doctor checks stop startup; a built binary alone does not mean the model is serving.
The checkpoint is baselabs/elephant-1 revision b3f8a93462fb1051a9de031e94a7ff380e254072. Its admitted model identity is elephant-1@sha256:682f02348dfe4617dd21bba2915c12e805de8cf16327a61e895a831ea681d0ba.
3. Prove your own Pylon
Wait for the online log and this success line:
Self-test passed: elephant-1 via <your public key>
The self-test sends a real encrypted decision through the relay, pins this join's own provider key and Elephant identity, and checks the returned answer. It prints the actual JSON result, then keeps the Pylon serving in the foreground. It does not borrow a hosted provider or fall back to another model.
Inspect the saved result and logs under ~/.openagents/pylon/state/elephant-1: self-test.json, fleet.log, engine.log and pylon.log. The profile retains its demo key and slug across restarts. Preserve that directory; do not publish its private state or demo-label file. The terminal also prints your public npub and Pylon name.
4. Find your Pylon
Choose Pylons and find the printed name. The board shows advertised model identity, public key, status and free slots. New signed announcements appear without a reload.
Give it a recognizable label and name on a later start:
bash /tmp/join-pylon.sh --model elephant-1 --self-test --label "My GPU" --slug my-elephant
Your own-provider self-test and the hosted API are separate paths. Appearing on the Grid does not automatically enroll your computer into /api/v1/systemone: hosted Elephant and Mammoth routes pin operator-approved provider keys and exact checkpoint identities. Use the native self-test above to prove your contribution.
Stop or restart
Press Ctrl-C in the join terminal. From another terminal:
bash /tmp/join-pylon.sh --model elephant-1 --stop
Repeat the learned join command to start again and reuse verified model files. An existing original checkpoint can be selected with --model-cache DIR; its files must still pass the pinned checks. Set OPENAGENTS_PYLON_HOME to change the checkout/cache/state root. A stopped Pylon can remain visible until its last beacon expires, at most five minutes.
Small toy test
For a machine without a qualified native GPU, choose the toy explicitly:
bash /tmp/join-pylon.sh --model psionic-toy
This lightweight network smoke test advertises psionic-toy; it downloads no Elephant checkpoint and makes no learned-model claim. Its state remains ~/.openagents/pylon/state. On a Mac it needs Command Line Tools; on Linux it needs Nix and GCC/G++.
Send a decision
The pooled production endpoint is POST https://openagents.com/api/v1/systemone. It accepts an authenticated OpenAgents session or a NIP-98 signed request. Anonymous requests are refused; model choices and free-demo usage are bounded by the service.
The full UTF-8 JSON request, including whitespace, is limited to 16 KiB. Responses are bounded to 256 KiB.
Save this decision request as /tmp/decision.json:
{"model":"elephant-1","state":"Water is wet.","questions":{"wet":{"type":"choice","instructions":"Is the water wet?","criteria":{"yes":null,"no":null}}}}
Use elephant-1 or mammoth-1 for the hosted demo. The returned service metadata identifies the selected model and provider. Unknown model names are refused; clients cannot choose a backend URL. Contributing compute and authenticating an API request are separate steps; you do not need an API credential to join.
Call from a terminal
Use an up-to-date OpenAgents checkout. If you joined with the default script, it is already at ~/.openagents/pylon. For an API-only checkout:
git clone --depth 1 --filter=blob:none --sparse https://github.com/OpenAgentsInc/openagents.git openagents-pylon
git -C openagents-pylon sparse-checkout set coax
cd openagents-pylon
On macOS the client needs Command Line Tools and Homebrew's secp256k1 and openssl@3 packages:
brew install secp256k1 openssl@3
On Linux, install a C compiler, pkg-config, and the libsecp256k1 and OpenSSL development packages. No Python or JavaScript runtime is needed by this client. An operator can set OA_MESH_SIGNER to an explicit prebuilt binary of the repository's existing sign.c helper.
From the checkout, run:
coax/web/api/mesh-client.sh --new-demo-key /tmp/decision.json
The helper builds the existing native NIP-98 signer if needed, creates a private disposable identity, signs the exact body and sends it over HTTPS. Its temporary key is removed when it exits. A new demo identity needs no prior account registration. It does not use your phone key or your Pylon's key.
A successful JSON response contains answers.wet.choice, service.provider and service.identity. Those identify the selected provider and checkpoint; they do not attest confidential execution or model correctness. A refusal is not a completed decision. 401 means authentication or replay, 429 a demo quota, 502 an upstream failure or mismatched result, 503 an unavailable model/provider, and 504 a deadline. Requests have a 30-second service deadline and there are identity and global demo limits; no sats are charged. API authentication grants demo access, without granting project membership or inference credit. Requests are readable by their selected model provider.
For staging, use coax/web/api/mesh-client.sh --staging --new-demo-key /tmp/decision.json. An existing local Nostr identity can instead use --key FILE; supply a file path, never a secret in a command argument.
Read the authenticated endpoint contract
Browser and custom clients
A signed-in browser on OpenAgents can POST the same JSON to /api/v1/systemone with its existing HttpOnly session cookie and same-origin request. Log in normally; you do not need to copy that cookie into a terminal.
A custom agent can use NIP-98 directly: sign a kind-27235 event with an empty content string and a current Unix timestamp. Include the exact absolute endpoint in its u tag, POST in its method tag, and the hex SHA-256 of the exact transmitted body in its payload tag. Send the complete signed event's JSON, Base64-encoded, as Authorization: Nostr <base64-event-json>. Events must be within 60 seconds and are single-use: sign a fresh event for each retry. The new event must have a different event ID: wait for a new timestamp or include a unique extra tag. Changing only the signature does not change the ID. A changed body, URL or method needs a newly signed event.
Confidential CPU proof
On 2026-10-30 a recovered immutable Clef worker completed a sealed NIP-44 decision on Google Confidential Space with Intel TDX, using CPU inference. The operator verified Google's certificate chain, admitted image, endpoint-key nonce and sealed receipt. The round took 8.404 seconds.
This is a dated capture, not a permanent liveness signal. The ordinary /api/v1/systemone route is readable by its selected provider. This confidential lane uses the separate NIP-ATT path and recovered historical worker/operator verifier. A Coax sealed client remains to be implemented; this record makes no confidential GPU claim. Fetch and verify fresh evidence before sealing new input.
Read the sealed-round report as JSON
Read the original signed records and attestation
Reproduce the dated operator verification
For agents
Read this exact guide as Markdown:
curl -fsSL https://openagents.com/docs/connect-a-pylon/index.md
1. Check native GPU/toolchain support and disk space, then run --model elephant-1 --self-test with a unique --label and --slug.
2. Preserve its working directory and private state. Keep its foreground process alive while serving; use Ctrl-C or bash /tmp/join-pylon.sh --model elephant-1 --stop when finished.
3. Confirm the known-answer doctor, own-provider relay self-test and online log. Inspect self-test.json and locate the public Pylon on the homepage; a build exit alone proves no contribution.
4. Authenticate separately before calling the pooled API. NIP-98 signs the exact POST URL, method and request-body digest; do not put a private signing key in a URL, log, prompt or public artifact.
5. Inspect the response's model/provider metadata and handle refusal or unavailable capacity rather than silently substituting another model.
Troubleshooting
If the first download or build is still running, leave the terminal open and read its current step. Repeat the same command after an interrupted download. Later runs reuse matching checked builds and authenticated model files.
If a GPU/toolchain probe refuses, fix that requirement or deliberately choose the toy command. Do not relabel a toy provider as Elephant. If it cannot connect, check outbound HTTPS and wss://relay.openagents.com, system time and certificate trust. A self-hosted relay can be selected with --relay; the public homepage watches the public OpenAgents relay.
If the computer is missing, confirm the online log line, the printed name and its beacon expiry. Use a unique slug. Expired advertisements stop contributing available capacity.
Include your OS, GPU/chip, model, exact command and nonsecret error logs when reporting a problem. Never attach private state or signing keys.
If a checkout has local edits, preserve them: deliberately use --no-update, use another OPENAGENTS_PYLON_HOME, or supply an existing checkout with --source DIR. Do not reset someone else's files. bash /tmp/join-pylon.sh --help is the executable option reference.
What is verified
The browser's shared Coax reader checks original Nostr event IDs and signatures, beacon content digests, provider binding and freshness. Hardware, model and capacity values remain provider advertisements, not hardware or model-execution attestation.
Answers and statuses count signed provider events observed since this tab opened. Their contents stay encrypted. They are not complete historical job totals, proof of a successful answer or payments. Pylons serving a request can read that request; use synthetic prompts for the demo.