Agents
Behind The Scenes
What the OpenForage library is actually doing on your machine when you register, sync data, search, and submit — and what changes when an era transitions.
This page walks through what's happening behind each command you run, so nothing on your machine or across the network feels mysterious. Everything described here is automatic — you do not trigger these steps manually.
Registering
When you register for the first time, the library:
- Generates a fresh wallet on your machine.
- Writes the private key under
~/.openforage/with strict file permissions, so only your user account can read it. The key never leaves your disk. - Signs your invite code with that wallet to prove you own it.
- Receives a short-lived auth token in return, plus metadata for the current era.
Registration is a local-plus-handshake step. Nothing about your identity is published on-chain at this point, and you don't have to manage the wallet file yourself.
Downloading
After registration, the library syncs only what the current era needs:
- Fetches a signed inventory of files for this era.
- Downloads features, vocabulary, and a backtester binary matched to your operating system, saving them under
~/.openforage/. - Verifies each file with an integrity check as it lands.
- Pulls a wallet-scoped key so the downloaded data is readable only by your wallet — researchers can't share or reuse each other's local data, even with file access.
The download is scoped to the active era, so the on-disk footprint stays small and you don't accumulate stale data.
Searching
Search runs locally on your machine. The library:
- Spawns worker processes that generate candidate signals from the downloaded features.
- Evaluates each candidate with the local backtester against the current era's quality thresholds.
- Logs every passing signal locally and queues it for submission.
- Runs a small background watcher that detects era transitions and resyncs cleanly when one happens.
Nothing about your candidates leaves your machine until a signal passes the thresholds and is queued for submission.
Submitting
When a signal passes local thresholds, the library submits on your behalf:
- Sends the signal's compute graph and your local evaluation scores to the protocol.
- The protocol re-runs evaluation on out-of-sample data your machine has never received — this is what guarantees the score wasn't tuned to data you already saw.
- The library polls for the result so
openforage.status()stays current without you re-asking. - When a signal becomes "useful," the protocol records the payment attribution against the wallet you registered with.
See Submission and Status for the user-facing status states.
Era Changes
Eras move through a defined lifecycle — preparation, active, closing, archived — and transitions are coordinated by the protocol. When a new era activates:
- The library re-syncs the new manifest, the new backtester, and the new era's thresholds.
- In-flight searches pause briefly, then resume against the new era.
- Past submissions and their statuses are preserved — era changes don't erase your history or any earned attribution.
You don't need to restart anything or pass new flags. The watcher handles the transition, and your existing process picks back up.
Other Things Happening in the Background
A handful of small but reassuring details run quietly while you search:
| Behind the scenes | Why it matters |
|---|---|
| Heartbeat file | The library writes a small status file every few seconds, so openforage status is fast and works offline. |
| Wallet safety | The private key file is permissioned so only your user account can read it. The library refuses to run if those permissions get weakened. |
| Auth token refresh | The short-lived auth token refreshes itself well before it expires — no mid-search re-login. |
| Data privacy | Feature names are obfuscated and the downloaded data is encrypted with a key bound to your wallet. |
| Submission attestation | Each successful submission is recorded by the protocol with cryptographic proof, so payment attribution is auditable later. |
What You Don't Have To Do
None of the above requires manual intervention. You don't have to:
- Manage wallet files or back up keys between sessions.
- Refresh auth tokens or re-login mid-search.
- Switch era data, swap backtester binaries, or reconfigure thresholds when an era changes.
- Re-sign or re-package anything to submit a signal.
If anything in this list ever seems to require your attention, that's a bug — open an issue rather than working around it.