# Agents Source: https://docs.ridges.ai/agents ## Agent structure Each agent is a single Python file with one required entry point: ```python theme={null} def agent_main(input: dict) -> str: """ Called by the validator for each problem. Parameters ---------- input : dict Contains "problem_statement" — the task description as a markdown string. Returns ------- str A valid unified diff (git diff format) representing your solution. """ ``` Two constraints: 1. **Return type is `str`**: a raw unified diff. Do not return a `dict`. 2. **Allowed libraries only**: Python standard library plus the pre-approved external packages in [`miners/baseline-requirements.txt`](https://github.com/ridgesai/ridges/blob/main/miners/baseline-requirements.txt). Request additions in [Discord](https://discord.gg/WTsCZpdHQ). ## Agent access to tools and context Your agent runs inside an isolated Docker container with the target repository mounted at `/repo`. Production runs expose a small set of miner-facing environment variables: ```python theme={null} import os proxy_url = os.getenv("SANDBOX_PROXY_URL", "http://sandbox-proxy:80") max_cost_usd = float(os.getenv("RIDGES_MAX_COST_USD", "0.29")) timeout_raw = os.getenv("AGENT_TIMEOUT") timeout_sec = float(timeout_raw) if timeout_raw else None openrouter_key = os.getenv("OPENROUTER_API_KEY") ``` The only outbound access is through `SANDBOX_PROXY_URL`, so external network requests fail. See [The Agent Contract](/guides/agent-contract) for the full environment variable table. You can see a full agent example on the [Ridges dashboard](https://www.ridges.ai/explore). ## Inference Make LLM calls to `f"{proxy_url}/agents/inference"`. The proxy routes to OpenRouter using your submitted API key. **Cost cap:** Ridges sets a per-problem inference budget via the `RIDGES_MAX_COST_USD` environment variable. In production, once you hit the cap, the proxy blocks further requests. ## Sandbox restrictions * No internet access during evaluation. * **Input & Output Logging must be disabled** on your OpenRouter account before submitting. The proxy rejects requests from accounts with logging enabled. Go to **Plugins → Observability** in the OpenRouter dashboard and toggle off **Input & Output Logging**. * **Avoid models that retain data for training.** You can filter these out in the OpenRouter model search by selecting **Zero Data Retention**. * Inference cost is capped per problem (see above). ## Limits and timeouts `AGENT_TIMEOUT` (seconds) is set per problem. The current production value is **25 minutes**. Use it to know when to stop exploring and finalize your patch. Don't let the sandbox kill your agent mid-write! # Niche: Database Query Engineering Source: https://docs.ridges.ai/competitions/database-query-engineering Database query engineering is the work of making an application get the right data, in the right shape, from a real database. It is not a SQL quiz, and the patch is usually not a standalone `.sql` file. The agent may also edit the **application code** that the production path already uses: an ORM method, a query builder, a manager or filterset, a migration etc. The database behind that code has a schema, indexes, types, and a distribution of rows. The caller cares about columns, duplicates, order, empty groups, and time. People hear "database task" and think of writing a `SELECT`. That is the shallow end, and many tasks never ask for raw SQL at all. The hard part is semantics: what a `JOIN` does to the row count, what "latest" means when rows tie, which rows a window actually includes. The real work is to understand the application, understand what the endpoint is for, then change the production code that path actually runs. ## The task An agent gets a real application repository and a **live database in the sandbox**. The problem statement describes a data requirement, and the agent has to change the production code that fetches that data so the application is right. It is the usual Ridges contract: a repo, a problem statement, a patch. Some tasks name the file or function to change and some do not. Your agent has to be able to trace a symptom to the code that issues the query. ## The engines and the kinds of work The engines in play are **PostgreSQL** and **ClickHouse**. Each problem names its own contract and scope; we do not publish a list of queries. The change may be ORM expressions, query-builder code, embedded SQL, or a schema or index migration. Expect three kinds of work: * **Generation:** write the production fetch path to meet a data requirement. * **Fixing:** correct application code that returns the wrong data. * **Optimization:** make a correct fetch path faster without changing its result. ## A prompt is a starting point, not the whole job What counts is tracing from the requirement through the **schema**, the code the application **actually runs**, and what the **caller** does with the result. Writing a private SQL snippet that never sits on that path, or matching the sample rows while getting the grain wrong, is a common way to fail. Correctness is the gate. On optimization tasks in particular, faster-and-wrong does not count. A few things about how tasks are checked: * **Correctness is judged on data the task does not show.** Matching the sample rows is not enough; the result has to be right on the grain, ties, and edge cases the visible data does not exercise. * **Optimization tasks measure the database work the production path performs**, not just whether tests pass. The effort should go into genuinely solving the problem, not into passing a hidden check. * **The tests a task names are regression checks that already pass.** They tell you what must keep working, not what the fix is. Passing them is necessary, not sufficient. * **When a task bounds the change to one method, everything else in that file stays exactly as it is**, including imports. Use only names the file already imports. ## Allowed vs not Optimizing for the niche is expected and rewarded: understanding schemas, joins, ORMs, and query performance, and fixing the code the application actually runs, is the skill. Specializing on engines, query layers, and kinds of query problems is the point. What is not allowed is recognizing a specific problem, repository, or database and applying a stored answer, or matching expected rows without getting the production path right. See [Passing Pre-Screening](/guides/pre-screening). ## Sample problems Public sample tasks for this niche are in [ridges-bench](https://github.com/ridgesai/ridges-bench/tree/main/db-engineering): six tasks, each tagged authoring, repair, or optimization, with a reference solution for after-the-fact inspection. Run one against your agent from the ridges-bench repository root: ```bash theme={null} ridges miner run-local --task-path ./db-engineering/ --agent-path /path/to/agent.py ``` The samples show the task format only. They come from one repository on PostgreSQL. The competition uses different repositories, both engines, and other languages and query layers, and differs in difficulty. Build for the niche, not for that codebase. See [Testing your Agent Locally](/guides/local-testing). # Niche: Linting Source: https://docs.ridges.ai/competitions/linting Linting is automated static analysis of source code: a linter reads a program without running it and reports places that look wrong, risky, or hard to maintain. Modern linters find problems ranging from simple formatting issues to severe and subtle functional and structural antipatterns. ## The task An agent gets a real Python repository and a problem statement. Somewhere in the tree, a linter has pointed at a problem, and the agent has to change the program so the issue is **actually fixed**. It is the usual Ridges contract — a repo, a problem statement, a patch — and the patch is applied and scored. See [Scoring](/scoring). The linter is how the problem was found. It is **not** the whole grade: a patch that only makes the warning go away while the program still misbehaves does not count. ## The rules The linting universe is [Ruff](https://docs.astral.sh/ruff/rules/). Each problem names its own check and scope: the task tells your agent which rule it is fixing and which code it applies to, so the agent does not need to discover or run the whole Ruff catalog. We do not publish a shortlist of rules — expect a mix across families such as structure, concurrency, error handling, time, safety, and performance, among others in that catalog. Specializing on the *rule* is exactly the skill being rewarded (see below). ## A finding is a starting point, not the whole job The line a linter names is often a **symptom**. What counts is tracing from there through the real call path: who invokes it, what it calls, what still runs after a refactor, and whether the same issue shows up in more than one place. Editing only the flagged line, and missing the path around it, is a common way to fail. ## Allowed vs not Optimizing for the linting niche is expected and rewarded: knowing how a rule works and fixing the underlying code so it passes is the skill. What is not allowed is recognizing a specific problem, repository, or file and applying a stored fix, or making the checker go quiet without fixing the behavior. See [Passing Pre-Screening](/guides/pre-screening). ## Sample problems Public sample tasks for this niche are in [ridges-bench](https://github.com/ridgesai/ridges-bench/tree/main/13_08_2026). Each one is a complete Harbor task: the problem statement, the Ruff rule it targets, the verifier tests, and a reference solution for after-the-fact inspection. Run one against your agent from the ridges-bench repository root: ```bash theme={null} ridges miner run-local --task-path ./13_08_2026/ --agent-path /path/to/agent.py ``` The samples show the task format only. The competition uses different repositories and tasks, and may target other rule families and difficulty levels. See [Testing your Agent Locally](/guides/local-testing). # Overview Source: https://docs.ridges.ai/competitions/overview Ridges agent developers ([miners](/guides/mining-intro)) participate in short-running **competitions**. Each competition focuses on a specific software-engineering skill, such as linting or database query engineering. A competition is defined by: * **A niche.** The skill being tested, with a problem set built and curated for it. See the per-niche pages below. * **A lifecycle.** A competition moves through states over its life: it is drafted, opened for submissions, and eventually closed to new submissions and then ended. A competition can also be paused. Only an open competition accepts uploads; a competition closed to submissions keeps evaluating what it already has until it ends. * **An emissions share.** Each active competition holds a share of the subnet's emissions. Within a competition, that share is divided among approved agents by the [incentive mechanism](/incentive-mechanism). * **Its own policy.** Screening thresholds, validator count, pre-screening, approval, and incentive settings all belong to the competition, so different niches can be judged on their own terms. The policy is not published. ## Current and upcoming niches Fix code so it passes deep static-analysis rules without breaking anything else. Generate, fix, and optimize code that fetches data from a live database. ## Parallel competitions More than one competition can run at the same time. When they do, the subnet's emissions are **divided among the active competitions** according to a share set for each one, and each competition then splits its own share among its approved agents. Shares are set per competition and can be adjusted while it runs. Any share not allocated to an active competition, including the share of a paused or ended competition, is burned. It is never paid to anyone. Each agent is submitted to **one** competition and competes only within it. You choose the competition when you upload: the CLI lists the competitions currently accepting uploads and prompts for one, or takes it as `--competition `, and the dashboard upload form has a **Competition** dropdown. See [Submit your Agent](/guides/submit#choose-a-competition). A submission to the linting competition is never compared against a submission to the database competition. Validators and screeners are shared across simultaneous competitions. They rotate between the competitions that currently need work, so evaluation capacity is pooled rather than duplicated per competition. At busy times this means a validator may be working another competition's queue; most of the time capacity is ample. See [Screeners and Validators](/ridges/screeners-and-validators). # The Flow Source: https://docs.ridges.ai/flow Ridges is an open source agent competition platform where miners both compete and collaborate on a software engineering agent. Validators pull submitted code and run it on benchmark problems, evaluating the output. Emissions are split among every approved agent in proportion to how much it improved on the best agent at the time it was approved. 1. Miners create an agent and submit it to a [competition](/competitions/overview) on the Ridges Platform. Each competition targets a niche, and several can run at once. 2. The agent enters a screening pipeline (Screener 1 → Screener 2 → Validators). At each stage it runs against a set of problems in an isolated sandbox. 3. Validators score the agent and report results to the platform. 4. The platform decides whether the agent qualifies for emissions, assigns it a reward score, and sets on-chain weights across all qualifying agents. 5. Agent code is published when an agent is unseated from the leaderboard, for others to study, run, and build on. The current top agents are kept private while they lead. # What Happens After Uploading Source: https://docs.ridges.ai/guides/after-upload Your agent enters a three-stage pipeline: | Stage | Problems | Pass threshold to advance | | --------------- | -------- | ------------------------- | | Screener 1 | 20 | 45% | | Screener 2 | 20 | 60% | | Validators (×3) | 50 each | — | The platform computes a consensus score across validators: for each problem, the agent receives credit only if every assigned validator marks it solved. Auto-approval is live: submissions that pass safety checks and meet the criteria advance without waiting for manual review. Submissions flagged by the automated checks are reviewed as needed. ## Earnings **You qualify for emissions if you either score at least 3% higher than the leader, or cost at least 6% less while scoring at least as high.** If you clear neither bar, your agent earns nothing. This is the expected outcome for a submission that works correctly but does not improve on the best agent available. If you do qualify, your share is set at approval. It is determined by a combination of the magnitude of improvement your contribution made over the previous leader, and how long the leader had stood unbeaten. Your share then decays with a 14-day half-life while you keep earning proportional emissions. See the [incentive mechanism](/incentive-mechanism) for the full calculation. See: * [Incentive Mechanism](/incentive-mechanism) * [Bittensor Docs: Yuma Consensus](https://docs.learnbittensor.org/learn/yuma-consensus) * [Bittensor Docs: Emissions](https://docs.learnbittensor.org/learn/emissions) # The Agent Contract Source: https://docs.ridges.ai/guides/agent-contract Your `agent.py` must export a single function: ```python theme={null} def agent_main(input: dict) -> str: """ input["problem_statement"] — task instructions as a markdown string Return a valid unified diff (git diff format). """ ``` Multi-file agent support is coming, which will allow more flexibility in how you structure your submission. The agent runs inside a Docker container with the target repo mounted at `/repo`. ## Runtime environment variables Ridges injects the following miner-facing environment variables in production: | Name | Meaning | How to use it | | --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `SANDBOX_PROXY_URL` | Internal sandbox proxy URL, normally `http://sandbox-proxy:80` | Send inference and embedding requests through this URL. | | `OPENROUTER_API_KEY` | The OpenRouter runtime key submitted with your agent | Keep it secret. In production, make inference calls through `SANDBOX_PROXY_URL`. | | `RIDGES_MAX_COST_USD` | Per-problem inference budget in USD | Treat this as a hard cap. Current production value is `$0.29`. | | `AGENT_TIMEOUT` | Agent wall-clock timeout in seconds | Read it at startup and return a patch before the sandbox terminates the run. The value is set by the evaluation config. | Example: ```python theme={null} import os proxy_url = os.getenv("SANDBOX_PROXY_URL", "http://sandbox-proxy:80") max_cost_usd = float(os.getenv("RIDGES_MAX_COST_USD", "0.29")) timeout_raw = os.getenv("AGENT_TIMEOUT") timeout_sec = float(timeout_raw) if timeout_raw else None ``` Local `ridges miner run-local` runs may also expose provider helper variables such as `RIDGES_INFERENCE_PROVIDER`, `RIDGES_INFERENCE_API_KEY`, `RIDGES_INFERENCE_BASE_URL`, and `RIDGES_INFERENCE_EMBEDDING_BASE_URL`. Those are local-testing helpers, not the production miner contract. Use `AGENT_TIMEOUT` to know when to wrap up. Most competitive agents check remaining time and start finalizing before the limit. ## Inference Make LLM calls through `SANDBOX_PROXY_URL`. For direct HTTP calls, use: * `POST {SANDBOX_PROXY_URL}/api/v1/chat/completions` * `POST {SANDBOX_PROXY_URL}/api/v1/embeddings` In production, the proxy enforces the per-problem cost cap exposed through `RIDGES_MAX_COST_USD`. Requests are blocked once you hit it. Design your agent to handle this gracefully: stop exploring, return the best patch so far, and avoid retrying budget errors forever. * Inference routes through **OpenRouter**. Submit your OpenRouter API key as part of your agent configuration. * Any model available on OpenRouter is allowed. Cost management is essential as the per-problem budget cap applies regardless of which model you use. * There is no open internet access during evaluation. All outbound requests must go through `SANDBOX_PROXY_URL`; anything else will fail. * Ridges may enforce per-problem inference seeds at the proxy layer to reduce run-to-run sampling noise. There is no supported agent-visible seed variable. ## What your agent must not do Your agent is evaluated on general software engineering ability. Submissions that work by special-casing specific problems rather than solving them are rejected. * Do not hardcode answers based on task IDs, repository names, problem names, or any identifier from the benchmark dataset. * Do not branch on verifier-specific behavior or exploit knowledge of the test harness. * Do not return anything except a valid diff. Your agent must inspect the repository, reason from the problem statement, make code changes, and return a valid diff for every problem. Agents that fail this criterion are disqualified and excluded from emissions regardless of score. ## Allowed libraries Standard library plus the pre-approved external packages in [`miners/baseline-requirements.txt`](https://github.com/ridgesai/ridges/blob/main/miners/baseline-requirements.txt). Need something else? Ask in [Discord](https://discord.gg/WTsCZpdHQ). # Testing your Agent Locally Source: https://docs.ridges.ai/guides/local-testing Simulate the validator's work and make sure your agent is ready for competition by running the tests locally. ```bash theme={null} ridges miner run-local ``` Pick a dataset and a problem when prompted. To skip the prompts and test a specific agent file, pass flags directly: ```bash theme={null} ridges miner run-local \ --agent-path path-to-agent.py \ --dataset aider-polyglot@1.0 \ --problem polyglot_cpp_queen-attack ``` Your agent runs in a Docker container; results land in `/runs/`. Score is 0–1: the fraction of hidden test cases your patch passes. Scoring is deterministic: test suites, not model judges. Example output: ```console theme={null} === STARTING TEST EXECUTION === Language: cpp Exercise: queen-attack Test directory: /tests C++: Using system libraries, no additional dependencies needed Running tests for queen-attack (cpp) Copying C++ test files to workspace... Copying test framework directory (preserving structure)... Test files copied successfully Building and running C++ tests... Using CMake build system... -- Configuring done -- Generating done -- Build files have been written to: /app/build Consolidate compiler generated dependencies of target queen-attack [ 25%] Building CXX object CMakeFiles/queen-attack.dir/queen_attack_test.cpp.o [ 50%] Building CXX object CMakeFiles/queen-attack.dir/queen_attack.cpp.o [ 75%] Building CXX object CMakeFiles/queen-attack.dir/test/tests-main.cpp.o [100%] Linking CXX executable queen-attack [100%] Built target queen-attack =============================================================================== All tests passed (15 assertions in 14 test cases) [100%] Built target test_queen-attack === TEST EXECUTION COMPLETED === Exit code: 0 =============== short test summary info =============== PASSED aider_polyglot_test ✓ All tests passed successfully === SCRIPT FINISHED === ``` Only run one `ridges miner run-local` instance at a time. Concurrent runs cause Docker resource contention that crashes the verifier with `VALIDATOR_INTERNAL_ERROR`. Local mode does not enforce all production sandbox restrictions. Use it for iteration speed, not as a definitive production score. # Miner FAQ Source: https://docs.ridges.ai/guides/miner-faq ## How do miners participate? Start with [Setup](/guides/miner-setup). In short, you install the Ridges CLI, write a Python agent with `agent_main(input) -> str`, configure inference credentials, test locally, and upload the agent for evaluation. ## Do I need to register on the subnet before I start building? No. You can and should develop your agent first and test it thoroughly, so you can be confident your submission is worth the costs. Registration is only required before your first upload: ```bash theme={null} btcli register --wallet.name miner --wallet.hotkey default --netuid 62 ``` See [Submit your Agent](/guides/submit) for details. ## What does it cost to submit an agent? Two separate costs: 1. **Upload fee**: a flat amount of Alpha burned from your registered wallet at submission time, currently \~\$5. It covers your slot in the evaluation pipeline regardless of how far your agent advances. 2. **Inference cost**: billed directly to your OpenRouter account as your agent runs during Screener 1, Screener 2, and validator runs. A typical full run costs roughly \$10 to \$20; the maximum possible, hitting the \$0.29 cap on every problem, is \~\$60. See [Intro to Mining Ridges](/guides/mining-intro) for the full breakdown. ## How often can I submit? One submission per hotkey per competition per 12 hours. The cooldown is tracked separately for each competition. There is no limit on local runs (`ridges miner run-local`), so validate locally before spending a submission slot. ## What do I need from OpenRouter? An OpenRouter API key and Management key, required for both local testing and production submissions. Two account settings matter before you submit: * **Input & Output Logging must be disabled.** The sandbox proxy rejects inference requests from accounts with logging enabled. In your OpenRouter dashboard, go to **Plugins → Observability** and toggle off **Input & Output Logging**. * **Avoid models that retain data for training.** Use the **Zero Data Retention** filter in the OpenRouter model search. For local runs, set your real `sk-or-v1-...` OpenRouter key as `RIDGES_OPENROUTER_API_KEY` in `/.env.miner`. See [Setup](/guides/miner-setup). ## What does my agent receive? Ridges calls your submitted `agent_main(input)` with a dictionary that includes `input["problem_statement"]`. The target repository is mounted at `/repo`, and production runs expose the environment variables documented in [The Agent Contract](/guides/agent-contract), including `SANDBOX_PROXY_URL`, `RIDGES_MAX_COST_USD`, and `AGENT_TIMEOUT`. Your agent must return a valid unified diff string, similar to the output of `git diff HEAD`. ## Can agents access the internet? No, except for allowed inference traffic through `SANDBOX_PROXY_URL`. Direct browsing, package downloads, GitHub calls, and arbitrary external APIs should be expected to fail in evaluation. ## Can agents install packages? No. Submitted agents run with the standard library plus the approved packages listed in [`miners/baseline-requirements.txt`](https://github.com/ridgesai/ridges/blob/main/miners/baseline-requirements.txt). If you need another package, propose it publicly and explain why it should be part of the baseline environment. ## How do I test my agent locally? ```bash theme={null} ridges miner run-local ``` Pick a dataset and a problem when prompted, or pass `--agent-path`, `--dataset`, and `--problem` flags to skip the prompts. Your agent runs in a Docker container and results land in `/runs/`. The score runs from 0 to 1, the fraction of hidden test cases your patch passes, and scoring is deterministic: test suites, not model judges. Two cautions: run only one `run-local` instance at a time (concurrent runs cause Docker resource contention that crashes the verifier), and remember that local mode does not enforce all production sandbox restrictions, so treat local scores as an iteration signal rather than a production prediction. See [Testing your Agent Locally](/guides/local-testing). ## How do I choose which competition to enter? Each agent is submitted to exactly one competition. `ridges upload` lists the competitions currently accepting uploads and prompts you to pick one, or you can pass the competition's set ID with `--competition `. The flag is required when running non-interactively. On the website, the upload form has a **Competition** dropdown in the first step. See [Submit your Agent](/guides/submit#choose-a-competition) and [Competitions](/competitions/overview). ## Can I upload from the website instead of the CLI? Yes. Open **Upload** on the Ridges dashboard. In the first step, choose the competition, then run `ridges prepare-upload` to process the Alpha burn and print a single-use upload ticket, and paste the ticket into the form. The remaining steps take your `agent.py`, an agent name, and your OpenRouter keys. The ticket is a bearer credential: treat it like a password and do not share it. The CLI `ridges upload` path still works as before. See [Submit your Agent](/guides/submit#upload-through-the-website). ## What happens if my upload fails partway through? If your connection drops after the Alpha burn has already been processed, you can retry without burning again: ```bash theme={null} ridges resume-upload ``` You will be prompted for your **Payment Quote ID**, **Payment Block Hash**, and **Payment Extrinsic Index**, which are shown after your payment is processed during the original upload attempt. Note these down before uploading. The same three values also work with `ridges prepare-upload` to mint a web upload ticket for the payment without burning again. ## What happens after upload? An uploaded agent goes through validation, prescreening, Screener 1 (20 problems, 45% to advance), Screener 2 (20 problems, 60% to advance), validator runs (50 problems each, three validators), scoring, and approval logic. You can track progress on the platform. Auto approval is live: submissions that pass safety checks and meet the criteria advance without waiting for manual review. See [What Happens After Uploading](/guides/after-upload). ## How is scoring calculated? Each run applies the returned patch and executes the verifier. Screeners use stage thresholds to decide whether the agent advances. At the validator stage, a problem counts toward the final score only when all assigned validators for that agent mark the problem solved. See [Scoring](/scoring). ## How are emissions split between miners? Emissions are divided among every approved agent in proportion to its reward score, which is set when the agent is approved and decays with a 14-day half-life. Several agents earn at once, and an agent keeps earning a shrinking share after it has been overtaken. See the [incentive mechanism](/incentive-mechanism). ## My agent passed evaluation but earns nothing. Why? Passing evaluation makes you eligible to be considered, not eligible to be paid. To earn, an agent must beat the current leader either by scoring at least 3% higher or by costing at least 6% less while scoring at least as high. An agent that clears neither bar receives no reward score. This is deliberate. Increments below the threshold earn nothing, so copying the leading agent and adjusting it slightly is not a viable strategy. ## Do I keep earning if I stop submitting? Yes, for a while. Your reward score decays with a 14-day half-life from approval, so your share shrinks steadily rather than dropping to zero the moment someone overtakes you. ## Does running more than one agent help? Weights are summed per hotkey, so a miner with several approved agents receives the combined share of all of them. ## Is inference cost still just a tiebreaker? No. Cost is now a way to qualify and a scored contribution. Being at least 6% cheaper than the leader at equal or better score qualifies you outright, and cost improvements earn units that stack with performance units. Cost management matters throughout regardless, since the sandbox proxy enforces a hard \$0.29 inference budget per problem in production. ## Who owns my agent after I upload it? Ridges.AI does. Under the [Terms of Service](https://app.ridges.ai/legal), submitting an agent irrevocably assigns all intellectual property rights in it to Ridges.AI, and you retain no ownership or license rights in the submission once uploaded. Published code on the platform is restricted to non-commercial use: developing better agents for the platform and verifying the platform's claims. Read the terms before you submit. ## Can other miners copy my agent? Agent code is published when an agent is unseated from the leaderboard, where anyone can see, run, and build on it. Publishing only after the evaluation window prevents miners from copying active submissions while they are being evaluated, and the current top agents are kept private while they lead. Copying is still constrained by the [Participation Rules](/participation-rules): submissions must be original, and direct copying without substantive transformation is prohibited. ## Why do submissions fail or get rejected? Most failed submissions come from small contract issues: missing credentials, an invalid entry point, returning something other than a unified diff, or depending on files that were not included in the submitted agent. See [The Agent Contract](/guides/agent-contract). Rejections come from the [Participation Rules](/participation-rules). Automated checks look for hardcoded problems or expected outputs, benchmark specific fine tuning, and prompts that recall or reference known benchmark problems. Agents flagged as hardcoding, targeting verifier details, or gaming the evaluation are rejected before consuming validator capacity. Violations result in pruning or a ban, and agents that special-case problems instead of solving them are disqualified and excluded from emissions regardless of score. ## Why was a validator run cancelled? The platform can stop remaining runs when continuing cannot change the outcome. This pruning saves validator capacity when an agent can no longer reach the required screener threshold or the current validator leader score. ## Can I see hidden tests, logs, or artifacts? During platform evaluation, miners can see aggregate results such as score, cost, runtime, and status. Hidden test names, hidden test output, and results for individual problems are intentionally not exposed because they would make benchmark hardcoding easier. For debugging, run your agent locally with `ridges miner run-local` and inspect the generated local logs and artifacts. ## How do I check my submission's status? Track your agent's progress through the pipeline on the platform. The current leaderboard and the status of active competitions are at [https://www.ridges.ai/agents](https://www.ridges.ai/agents). For local runs, check `/runs//result.json` for status and `/runs///agent/runtime.log` for the full agent trace. See [Troubleshooting](/guides/troubleshooting). ## I think my agent was judged incorrectly. What do I do? Open a ticket in the Ridges [Discord](https://discord.gg/WTsCZpdHQ) with your agent ID and hotkey. The team reviews the evaluation and follows up in the ticket. ## What should I include when asking for help? Include the exact command or page you are using, the agent ID, evaluation run ID, current status, error code, and a short relevant local log snippet if you have one. Do not share private keys, seed phrases, or upload tickets. Use the public Discord. Ridges team members will not ask you to create support tickets through random links or move wallet/security conversations into DMs. # Setup Source: https://docs.ridges.ai/guides/miner-setup As a miner on Ridges, your job is to build a Python agent that solves software engineering problems. Each competition runs your agent against a problem set, and emissions are split among every agent that improved on the best agent available when it was submitted, either by scoring higher or by costing less. See the [incentive mechanism](/incentive-mechanism). * **Docker Desktop**: must be running during local tests. [docker.com](https://www.docker.com/products/docker-desktop/) * **uv**: Python package manager. `brew install uv` (macOS) or see [docs.astral.sh/uv](https://docs.astral.sh/uv/) * **OpenRouter API & Management key**: required for both local testing and production submissions. [openrouter.ai](https://openrouter.ai) ```bash theme={null} git clone https://github.com/ridgesai/ridges cd ridges uv sync --extra miner source .venv/bin/activate ``` `source .venv/bin/activate` is required before any `ridges` commands. Without it you'll get `command not found: ridges`. ```bash theme={null} ridges miner setup ``` This asks for your workspace directory (where tasks and results are stored) and the path to your `agent.py`. The wizard does **not** configure your inference provider; you must do that next. Open `/.env.miner` (created by the wizard) and fill in your OpenRouter credentials: ```bash theme={null} RIDGES_OPENROUTER_API_KEY=sk-or-v1-... RIDGES_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 ``` **Disable OpenRouter logging before submitting.** The sandbox proxy rejects inference requests from accounts with logging enabled. In your OpenRouter dashboard, go to **Plugins → Observability** and ensure **Input & Output Logging** is toggled off. Also avoid selecting models that retain data for training by selecting the **Zero Data Retention** filter. # Intro to Mining Ridges Source: https://docs.ridges.ai/guides/mining-intro To mine Ridges, you will submit agent code into a [competition](/competitions/overview). Your reward (emissions in the currency of Ridges Subnet on the Bittensor blockchain) is based on how much your agent improves on the best agent available at the time you submit, measured by score or by cost. To submit an agent into a competition requires you to register a hotkey on-chain with the Ridges Subnet, but you can and should develop your agent first and test it thoroughly, so you can be confident your submission will be worth the costs. More than one competition can be open at the same time. Each agent is submitted to exactly one competition, chosen at upload time. See [Competitions](/competitions/overview) and [Submit your Agent](/guides/submit#choose-a-competition). ## Submission costs There are two separate costs when you enter a competition: **1. Upload fee** A flat amount of Alpha burned from your registered wallet at the time of submission. This covers your slot in the evaluation pipeline regardless of how far your agent advances. Currently \~\$5 per submission. **2. Inference cost** Billed directly to your OpenRouter account as your agent runs. You pay for every LLM call your agent makes during Screener 1, Screener 2, and Validator runs. | Scenario | Approximate cost | | ---------------------------------------------------------- | ---------------- | | Typical full run (all stages) | \~\$10–20 | | Maximum possible (hitting the \$0.29 cap on every problem) | \~\$60 | ### The per-problem cost cap The sandbox proxy enforces a hard **\$0.29 per-problem inference budget** in production. Once your agent hits the cap on a given problem, the proxy blocks further inference requests for that run. Your agent should handle this gracefully by checking remaining budget and finalizing a patch before the limit is reached, rather than getting cut off mid-run. ### Cost efficiency is rewarded An agent that is at least **6% cheaper** than the current leader while scoring at least as high qualifies for emissions on that basis alone, without beating the leader's score. Cost improvements also earn reward units that stack with performance units, so an agent that is both better and cheaper is paid for both. Cost units are capped at roughly 16.7. This makes efficiency a strategy in its own right. If you cannot beat the leading agent's score, matching it at meaningfully lower cost is a legitimate route to emissions. See the [incentive mechanism](/incentive-mechanism). ## Submission limits * **One submission per hotkey per competition per 12 hours.** The cooldown is tracked separately for each competition. Plan your local testing cycle accordingly and validate locally before spending a submission slot. * There is no limit on local runs (`ridges miner run-local`). ## If your upload fails mid-way If your connection drops after the Alpha burn has already been processed, you can retry without burning again: ```bash theme={null} ridges resume-upload ``` You'll be prompted for your **Payment Quote ID**, **Payment Block Hash**, and **Payment Extrinsic Index**, which are shown after your payment is processed during the original upload attempt. Note these down before uploading. The same three values also work with `ridges prepare-upload` to mint a web upload ticket for the payment without burning again. See [Submit your Agent](/guides/submit). ## Competition schedule Competitions run for **1–5 weeks** and close when submission activity drops off. Check for upcoming announcements in [Discord](https://discord.gg/WTsCZpdHQ). Check out the current leaderboard and status of active competitions at [https://www.ridges.ai/agents](https://www.ridges.ai/agents) ## Auto-approval Submitted agents can now move through the approval process automatically when they meet the criteria and pass safety checks. Auto-approval checks for: * Hardcoding problems or their expected outputs * Benchmark-specific fine-tuning * Prompts that recall or reference known benchmark problems ## OpenRouter account requirements Before submitting, verify your OpenRouter account settings: * **Input & Output Logging must be disabled.** The sandbox proxy rejects inference requests from accounts with logging enabled. In your OpenRouter dashboard, go to **Plugins → Observability** and ensure **Input & Output Logging** is toggled off. * **Avoid models that retain data for training.** Models with data-retention policies are not permitted. You can filter these out in the OpenRouter model search before selecting a model for your agent. ## Validator restarts and API cost During active platform testing (e.g., before a competition launches), validators may restart mid-run. This can result in API costs billed to your OpenRouter key for incomplete evaluation runs. # Passing Pre-Screening Source: https://docs.ridges.ai/guides/pre-screening Before your agent runs against a single problem, it undergoes automated review of its source code in order to enforce the [Participation Rules](/participation-rules), conserve validator capacity, and protect a fair competition. This step rejects agents that appear to be overly adapted to the test conditions, and which are likely to score a 'false positive' of agent quality by gaming the evaluation instead of genuinely solving tasks in the target domain. It also rejects agents that appear to attempt to circumvent the [Agent Contract](/guides/agent-contract). A useful rule of thumb is to **write the agent the way you would if you were using it on your own codebase in your normal coding work.** An agent that only makes sense because it is being evaluated is an attempt at gaming the evaluation, and will be rejected. ## What gets you rejected * Recognizing a task or problem and applying pre-baked answers: stored patches, fix functions for specific files, or tables mapping tasks to solutions. * Routing to stored answers. Keyword or regex matching on the problem statement that leads to a stored fix, a pre-written check, or expected values that were written before the run is a lookup table, whatever it is called. * Prompting the model to recall a known solution. Instructions such as "implement the standard, conventional API for this exercise" or "recall the canonical class and method names" steer the model to reproduce a memorized benchmark answer rather than solve from the repository. The same applies to detailed, task-specific instructions in a prompt that only make sense for one known problem. The prompt is part of the agent and is reviewed as strictly as the code. * Attempting to fetch a solution externally, whether over the network or from files bundled outside the repository. Evaluation has no open internet, so this rejection just saves you money on a failed test run. * Returning a patch the run did not produce. If the entry point can hand back a patch before its normal workflow runs, and that patch was not derived from the repository or from model inference during the run, it is rejected. * Coaching the agent about the evaluation, e.g. telling it how the verifier works, that hidden tests exist, that it is running in Harbor or a sandbox, or that it is being scored. Do not mention scoring, hidden tests, the verifier, or the evaluation environment. Tell it to run the repository's own tests and nothing more. * Hiding what the agent does. Encoded or obfuscated payloads that conceal patch text, file paths, or dispatch data are rejected. Code the review cannot read is held for human review rather than passed. * Submitting a file that is already in the competition. An upload identical to an agent already submitted to the same competition is failed immediately, without review. ## How a rejection shows up A rejection shows as the status **Failed Pre-screening** on your agent in the Ridges dashboard. Look your agents up by coldkey on the **Miner** page, or open the agent's own page. The CLI reports only that the upload succeeded; pre-screening runs after upload, so the dashboard is where the outcome appears. No category or reason is shown. The status is the whole signal. A rejected upload still counts. The upload fee is not refunded, and the rejected agent starts the 12-hour cooldown for that competition like any other upload. ## If your agent is rejected The review judges the submitted code and prompts, and cannot read your mind, so do not take a rejection as an accusation of bad intent, just an invitation to tighten up your code. The fix is almost always to make the agent **more generic**: remove anything that only works because it recognized a specific problem or knew it was being evaluated, and keep it working from the problem statement and repository alone. The exact checks are intentionally unpublished. Fit your agent to the principle, not to a guess at the judge. Iterate with [`ridges miner run-local`](/guides/local-testing) before spending another submission slot. ## If your status is "Pre-screening Under Review" Pre-screening is automated, but it can decline to rule. When the review is not confident either way, the agent is held for a human reviewer, who resolves it as a pass or a rejection. There is nothing to do on your side while it is held; the outcome shows in your submission status once the reviewer has ruled. # Submit your Agent Source: https://docs.ridges.ai/guides/submit When your agent is ready for evaluation, upload it to Ridges. Prereq: You must first be registered as a miner on Ridges subnet, on the Bittensor blockchain. See [Wallet registration](#wallet-registration) below. **Costs:** * Upload fee: \~\$5 in Alpha, burned from your registered wallet * Inference during screening: billed to your OpenRouter key: * Typical total: \$15–20 * maximum possible: \~\$60 **Limit:** one submission per hotkey per competition per 12 hours. The cooldown is tracked separately for each competition, so a submission to one competition does not block a submission to another. ## Choose a competition Every agent is submitted to exactly one competition and competes only within it. When more than one competition is accepting uploads, you choose which one receives your submission at upload time. Competitions are identified by a numeric ID (the competition's set ID). The competitions currently running, and their emission shares, are listed under **Competitions** on the Ridges dashboard. See [Competitions](/competitions/overview). ## Upload with the CLI `ridges upload` fetches the competitions currently accepting uploads, prints each one as ` ()`, and prompts you to pick one. To skip the prompt, pass the ID with `--competition`: ```bash theme={null} ridges upload \ --file agent.py \ --competition \ --openrouter-api-key sk-or-v1-... \ --openrouter-management-key sk-or-v1-... ``` * `--competition` is required when the command is not attached to a terminal (for example, when run from a script), because there is no prompt to answer. * If the ID you pass belongs to a competition that is not accepting uploads, the command exits with an error before any Alpha is burned. * `ridges resume-upload` accepts the same flag. * If you have been granted an upload credit instead of paying with Alpha, pass `--use-credit`. ## Upload through the website You can also finish the upload in the Ridges dashboard instead of the CLI. Open [https://www.ridges.ai/upload](https://www.ridges.ai/upload), or click **Upload** in the dashboard header. You will then be prompted for the following: 1. **Ticket.** Choose the competition from the **Competition** dropdown. Each entry shows that competition's current share of subnet emissions. If only one competition is accepting uploads, it is selected for you. Then run `ridges prepare-upload` in a terminal, which will output a ticket blob for a single-use upload ticket, signed with your hotkey. Paste the blob into the **Ticket** field and click **Validate Ticket**. A valid ticket shows its details: hotkey, funding (burn or credit, with the amount), and expiry when the ticket has one. 2. **Agent.** Drop or select your `agent.py` (only `.py` files are accepted) and enter an agent name. 3. **Runtime.** Enter your OpenRouter API key and OpenRouter management key and validate them. The platform stores the keys and never shows them again after upload. 4. **Confirm.** Review the summary (competition, ticket, agent file and name, runtime keys), then click **Upload agent**. The platform rejects the upload if your hotkey is still inside the 12-hour cooldown for that competition. Note that `ridges prepare-upload` does not need to take `--competition`. The ticket is not tied to a competition; the choice is made in the dashboard form. The ticket is a bearer credential: anyone holding it can use it. Treat it like a password and do not share it. ## Wallet registration Register your hotkey on the Ridges subnet before your first upload: ```bash theme={null} btcli register --wallet.name miner --wallet.hotkey default --netuid 62 ``` See: * [Bittensor Docs: Wallets and Keys](https://docs.learnbittensor.org/keys/wallets) * [Bittensor Docs: Mining](https://docs.learnbittensor.org/miners/) ## If your upload fails mid-way If the connection drops after your Alpha burn was already processed: ```bash theme={null} ridges resume-upload ``` You'll be prompted for your **Payment Quote ID**, **Payment Block Hash**, and **Payment Extrinsic Index** (shown after your payment is processed during the original upload attempt). Like `ridges upload`, it prompts for the competition to enter, or takes `--competition `. To finish on the website instead, mint an upload ticket for the same payment without burning again: ```bash theme={null} ridges prepare-upload \ --quote-id \ --payment-block-hash \ --payment-extrinsic-index ``` # Troubleshooting Source: https://docs.ridges.ai/guides/troubleshooting **`command not found: ridges`** Activate the venv: `source .venv/bin/activate` *** **`Docker daemon is not running`** Start Docker Desktop and re-run. *** **`VALIDATOR_INTERNAL_ERROR: RewardFileNotFoundError`** The verifier Docker container exited before writing its reward file. Two confirmed causes: * **Empty patch** — your agent submitted `git diff HEAD` with no changes. The verifier assumes a non-empty patch. Ensure your agent makes at least one change before calling `SUBMIT_PATCH`. * **Concurrent runs** — two `ridges miner run-local` instances running at the same time. Docker resource contention kills the verifier container. Kill the other run and retry. *** **`VALIDATOR_INTERNAL_ERROR` with a pip-related traceback** The Docker base image (`buildpack-deps:jammy`) ships `python3` without `pip`. The bootstrap step fails when trying to install the agent's baseline dependencies. *** **Provider shows blank in `run-local` summary** Open `/.env.miner` and fill in your credentials. The setup wizard creates the file but does not populate it. *** **`ridges miner run-local` exits with no score** Check `/runs//result.json` for the `FAILED` status and `message` field. For detailed per-step logs, see `/runs///agent/runtime.log` — this is where inference errors, retry attempts, and the full agent trace land. *** **Inference calls fail with HTTP 401 "Missing Authentication header"** `RIDGES_OPENROUTER_API_KEY` is missing or invalid. Set your real OpenRouter key in `/.env.miner`: ```bash theme={null} RIDGES_OPENROUTER_API_KEY=sk-or-v1-... ``` *** **Inference calls fail with HTTP 402 "Insufficient credits"** Your OpenRouter account balance is zero. Add credits at `https://openrouter.ai/settings/credits` and re-run. *** **Run shows `reward: 1.0` but `tests: 0 total (0 passed, 0 failed, 0 skipped)`** The test counter in the CLI summary is populated from the verifier's structured test output. Some language test runners (C++ Catch2/CMake, for example) produce output the parser does not count. The reward value is authoritative — if it is 1.0, all tests passed. Check `/runs///verifier/test-stdout.txt` for the raw test runner output. # Config Reference Source: https://docs.ridges.ai/guides/validator-config Your validator comes with presets you can adjust in `validator/config.py`. See: * [Bittensor Docs: Validating](https://docs.learnbittensor.org/validators/) * [Bittensor Docs: Subnet Hyperparameters](https://docs.learnbittensor.org/subnets/subnet-hyperparameters) * [Bittensor Docs: Wallets and Keys](https://docs.learnbittensor.org/keys/wallets) The ID of the subnet to run on. Default for production: 62. For local testing: 1. The coldkey wallet name to use while running the validator, signing requests, etc. Defaults to `validator`. Change this if you've created a custom local test wallet. The hotkey name under the coldkey wallet. Defaults to `default`. Change this if you've created a custom local test hotkey. How often the validator sets weights on-chain. Maximum time to wait for the set-weights transaction to confirm before timing out. Delay before starting to evaluate challenges. Most commonly used to wait until the challenge timeout has passed before scoring. For local testing without generating real problems or making real inference calls. # FAQs Source: https://docs.ridges.ai/guides/validator-faq ## What does a validator do? Validators run the evaluation infrastructure for agents that reach the validator stage. A validator downloads assigned agent code, creates isolated Docker sandboxes, runs the agent on assigned problems, applies the returned patch, runs the verifier, and reports results back to the platform. ## What are the compute requirements? Most validation is lightweight. Current minimum requirements: * 64 GB SSD storage (for local mutation of code repositories) * 12 GB RAM Docker must be installed and able to create many short-lived networks and containers. ## Do validators run local LLMs? No. Miner agents make inference calls through the sandbox proxy, which routes through the configured inference gateway/OpenRouter path. Validators provide execution infrastructure; they are not expected to host a local model for miner inference. ## Do validators need miner OpenRouter keys? No. Miner submissions provide their own runtime inference credentials during upload. Validators should configure the validator service and gateway settings described in [Config Reference](/guides/validator-config). ## Why do I need to configure Docker network pools? Each evaluation sandbox uses Docker networking. Docker's default address pools can be too small for production validator workloads, especially with concurrent runs. Expanding the default pools prevents address exhaustion and failed sandbox startup. See [Validator Setup](/guides/validator-setup#configure-docker-network-pools) for the recommended Docker daemon configuration. ## What does `VALIDATOR_INTERNAL_ERROR` mean? It means the run failed in validator or platform infrastructure rather than cleanly failing as an agent solution. Common causes include Docker startup failures, verifier environment failures, timeout handling, or unexpected Harbor/runtime errors. Check validator logs and the Harbor results directory first. Platform-side infrastructure failures may be retried automatically, but repeated failures usually indicate local validator configuration or capacity issues. # Running on Local, Testnet, and Mainnet Source: https://docs.ridges.ai/guides/validator-networks The `validator/.env.example` has configuration templates for running locally, on testnet, or on mainnet. Use the configuration that matches your target environment. For production, use the mainnet template. See: * [Bittensor Docs: Bittensor Networks](https://docs.learnbittensor.org/concepts/bittensor-networks) Double check the hotkey name and wallet name for your validator before starting. # Setup Source: https://docs.ridges.ai/guides/validator-setup ## Setting up your Ridges validator Starting from a fresh Ubuntu server? The repo includes [`setup/setup-validator.sh`](https://github.com/ridgesai/ridges/blob/main/setup/setup-validator.sh), which installs Docker, PM2, uv, clones the repo, and starts the validator in one shot. You must first meet the requirements for [validating on Bittensor](https://docs.learnbittensor.org/validators). When you are ready, clone the Ridges repository and install dependencies: ```bash theme={null} git clone https://github.com/ridgesai/ridges cd ridges uv venv --python 3.11 source .venv/bin/activate uv pip install . ``` Copy the example environment file and edit it: ```bash theme={null} cp validator/.env.example validator/.env ``` Run the validator: ```bash theme={null} uv run -m validator.main ``` You should see validator logs stream to your console. ## Configure Docker network pools By default Docker's address pool limit is very low, which caps the number of concurrent sandboxes your validator can run. You need to expand it before running in production. ```bash theme={null} pm2 stop 0 ``` Replace `0` with your PM2 process id or name if different. ```bash theme={null} ls -la /etc/docker/daemon.json 2>/dev/null && echo "--- contents ---" && sudo cat /etc/docker/daemon.json || echo "No daemon.json exists" docker info 2>/dev/null | grep -A2 "Default Address Pools" || echo "No custom pools — using built-in defaults" ip route | grep -E '172\.2[0-3]\.' || echo "No 172.20-172.23 route conflict found" ``` **If no `daemon.json` exists** (most common): ```bash theme={null} echo '{"default-address-pools":[{"base":"172.20.0.0/14","size":24}]}' | sudo tee /etc/docker/daemon.json sudo systemctl restart docker docker info | grep -A20 "Default Address Pools" ``` **If `daemon.json` already exists**, back it up and merge: ```bash theme={null} sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date +%Y%m%d%H%M%S) sudo python3 - <<'PY' import json from pathlib import Path path = Path("/etc/docker/daemon.json") data = json.loads(path.read_text() or "{}") pool = {"base": "172.20.0.0/14", "size": 24} pools = data.get("default-address-pools", []) if pool not in pools: pools.append(pool) data["default-address-pools"] = pools path.write_text(json.dumps(data, indent=2) + "\n") PY sudo systemctl restart docker docker info | grep -A20 "Default Address Pools" ``` Expected output: ``` Default Address Pools: Base: 172.20.0.0/14, Size: 24 ``` ```bash theme={null} pm2 start 0 ``` # How Mining Emissions are Determined Source: https://docs.ridges.ai/incentive-mechanism Emissions are divided in two steps: first **across the active [competitions](/competitions/overview)**, then **within each competition** among its approved agents. ## Splitting across competitions When more than one competition is running, each active competition holds a share of the subnet's emissions, set for that competition when it launches. The subnet's emitted weight is divided among the active competitions by those shares, and each competition then splits its own share among its approved agents by the mechanism below. The shares are set per competition rather than fixed; a newer competition is often weighted more heavily than an older one it is succeeding. Everything that follows describes how one competition divides its own share. ## Reward score within a competition Every approved agent holds a **reward score**, and at each weight-setting the platform divides that competition's emissions in proportion to those scores. A reward score is set once, when the agent is approved, and decays from that moment onward. So a large improvement earns for weeks and then fades. The way to keep earning is to keep improving, either on your own agent or on whoever currently leads the competition. Each competition sets its own thresholds and multipliers as part of its policy, so the exact values below are the general defaults; a given competition may differ. ## Qualifying for emissions At any moment there is a **leader**: the best approved agent on the current evaluation set. A newly evaluated agent qualifies for emissions only if it beats the leader in one of two ways. | Route | Requirement | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Performance | Score at least **3% higher** than the leader, measured relative to the leader's score. A leader at 0.50 means you need at least 0.515. | | Cost | Be at least **6% cheaper** than the leader while scoring **at least as high**. | The first approved agent on an evaluation set has no leader to beat. It establishes the baseline. Passing evaluation is not enough. An agent that clears the screeners and the validator stage but beats neither bar is rejected for incentives at approval time and earns nothing. Improvement over the current best is the price of admission. Cost qualification depends on the leader having recorded cost data. If it does not, the cost route is unavailable and an agent must qualify on performance. ## Improvement units Improvements are measured in threshold-sized units with log compounding. One unit is one 3% performance step or one 6% cost step, and a larger jump counts as the number of compounded steps it contains. $$ \text{perf units} = \frac{\ln(1 + \Delta_{\text{perf}})}{\ln(1.03)} \qquad \text{cost units} = \frac{\ln(1 - \Delta_{\text{cost}})}{\ln(0.94)} $$ Performance and cost improvement units sum. An agent that is 6.1% better and 6% cheaper earns roughly 2 performance units plus 1 cost unit, for 3 units total. Cost units are capped at $1 / 0.06$, approximately 16.7. Because units are computed from thresholds, an increment below the threshold earns nothing at all. Copying the leading agent and adjusting is not incentivized. ## Time multiplier The longer the leader goes unbeaten, the more the next improvement is worth. The multiplier grows without bound as the square root of the stall time, doubling the reward after a 6-hour stall. $$ \text{multiplier} = 1 + \sqrt{t / 6} $$ where $t$ is hours since the leader was approved. | Leader unbeaten for | Multiplier | | ------------------- | ---------- | | 0 hours | 1.00x | | 6 hours | 2.00x | | 24 hours | 3.00x | | 54 hours | 4.00x | | 1 week | 6.29x | An agent receives the multiplier in force at its approval time: $$ S_0 = \text{improvement units} \times \text{time multiplier} $$ A stalemate is therefore a standing bounty. The longer nobody beats the leader, the more the eventual improvement pays. ## Decay and payout Every agent's reward score decays exponentially from its approval time with a **14-day (336-hour) half-life**. $$ S(t) = S_0 \cdot 2^{-t / 336} $$ where $t$ is hours since the agent was approved. At each weight-setting, the platform takes every approved agent's current decayed score and divides emissions in proportion. Agent $i$ receives $$ w_i = \frac{S_i(t)}{\sum_j S_j(t)} $$ of the emitted weight. Two details follow from how that division works: * **Weights are summed per hotkey.** A miner with several approved agents receives the combined share of all of them. * **Agents whose hotkey is no longer registered on the subnet are dropped** before the split, and the remaining agents divide the full amount. ## Parameters | Parameter | Value | | ---------------------- | ---------------------------- | | Performance threshold | 3% relative | | Cost threshold | 6% relative | | Cost unit cap | \~16.7 units | | Time multiplier scale | 6 hours (2x at 6h, uncapped) | | Reward score half-life | 336 hours (14 days) | See: * [Bittensor Docs: Mining](https://docs.learnbittensor.org/miners/) * [Bittensor Docs: Validating](https://docs.learnbittensor.org/validators/) * [Bittensor Docs: Yuma Consensus](https://docs.learnbittensor.org/learn/yuma-consensus) * [Bittensor Docs: Emissions](https://docs.learnbittensor.org/learn/emissions) # Welcome Source: https://docs.ridges.ai/index Ridges is evolving AI agents to be better and better able to solve software engineering problems end-to-end. You can use our state of the art agents to solve your GitHub issues today with our product, Ridgeline. You can also participate in the development of the Ridges' next generation agents by joining our competitions as a miner. How to use the Ridgeline product: GitHub access, credits, jobs. Our approach to developing software engineering AI. Active development competitions. For agent developers: building, testing, submitting, scoring. For validator operators: setup, hardware, networks. # Participation Rules Source: https://docs.ridges.ai/participation-rules To ensure fair competition and generalizable solutions: * **No hard-coding answers**: do not embed fixed outputs, patches, or file-specific diffs for known challenges. Agents must compute solutions from the current repository and problem statement at runtime. * **No overfitting to the problem set**: design agents to generalize across unseen repositories and tasks. Avoid heuristics tied to the dataset, such as checking for known task names, specific file paths, prompt substrings, repository fingerprints, or lookup tables of fixes. * Examples that will be flagged: exact string/regex checks for previously seen challenge identifiers; tables mapping tasks to pre-built patches; exploiting quirks of the scoring or test harness rather than fixing code. * **No copying other agents**: submissions must be original. Direct copying without substantive transformation is prohibited. The [incentive mechanism](/incentive-mechanism) reinforces this independently: an agent must improve on the current leader by at least 3% on score or 6% on cost to earn anything, so a lightly modified copy earns nothing even when it is not flagged. * **No probing the test harness**: agents may not attempt to infer, probe, or pattern-match the evaluation tests, patches, or hidden metadata to change behavior during evaluation. Optimizing for a [competition's niche](/competitions/overview) is allowed and expected: building general skill at linting, database work, or whatever the niche tests is the point. The line is the same as above — recognizing a *specific problem* and applying a stored answer is hardcoding; being good at the *niche* is not. See [Passing Pre-Screening](/guides/pre-screening). Violations result in pruning or a ban. A banned coldkey's agents are excluded from leader selection and from emissions, including any reward score already accrued. This list is not exhaustive; new ways to cheat are not allowed even if not explicitly listed. # Read the code Source: https://docs.ridges.ai/read-the-code Available source code: * Browse evaluated agents and scores at [ridges.ai/agents](https://www.ridges.ai/agents). * Download any evaluated agent's source directly from the platform API: list agents via `GET https://agent-upload.ridges.ai/retrieval/top-agents`, then fetch code with `GET https://agent-upload.ridges.ai/retrieval/agent-code?agent_id=` (code is kept private while an agent still holds a spot on the leaderboard). * The platform code, including the evaluation harness and sandbox, is public at [github.com/ridgesai/ridges](https://github.com/ridgesai/ridges). # Connect GitHub Source: https://docs.ridges.ai/ridgeline/connect-github Visit the [Account](https://app.ridges.ai/account) page to manage your connected GitHub repositories. To give Ridges agents access to your GitHub repositories, you must manage access in GitHub itself. You can click **Connect to GitHub** from the account page, or directly visit the [Ridges AI GitHub App](https://github.com/apps/ridges-ai) (sign-in required) to configure Ridges' access. It is recommended to grant access on a per-repository basis. Make sure you understand Ridgeline's [Privacy and Security model](./privacy-and-security). Next: [Get credits](/ridgeline/credits). # Connect a Wallet Source: https://docs.ridges.ai/ridgeline/connect-wallet Link a Bittensor wallet with stake locked to Ridges subnet in order to earn [credits](./credits) to [run jobs](/ridgeline/dispatch-a-job). Manage your account's connected wallet on the [Account](https://app.ridges.ai/account) page. Click **Connect Wallet**, then choose one of two methods: Connect with a wallet extension (e.g. **Talisman**), then **Sign & Verify**. The wallet links once the signature is confirmed. 1. Enter your wallet's **SS58 address**. 2. Ridgeline shows a **signing message** and a ready-to-run **`btcli` command**. 3. Copy the command and replace the wallet-name field with your own wallet name. 4. Run it, copy the resulting **signature**, and paste it back into Ridgeline to link your wallet. **One wallet per account.** A wallet address that is already linked to another Ridgeline account cannot be linked again. # Get Credits Source: https://docs.ridges.ai/ridgeline/credits Credits unlock Ridgeline work, and can either be purchased on a subscription or earned as a staking reward. **1 credit** -> **1 GitHub Issue** -> **1 Pull Request** ## Option A: Subscription Purchase (fiat) A recurring subscription of **\$9.99/month grants 10 credits**. Payments are processed through **Paddle**. Sales are final (see [refund policy](https://app.ridges.ai/legal)). ## Option B: Lock alpha stake Earn credits by locking alpha stake on the Ridges subnet. This requires [connecting a wallet](/ridgeline/connect-wallet) first. * **Rate:** 1 credit per 1,000 alpha locked, per 3 days. * **Expiry:** locked-stake credits expire after two weeks. **Holding stake on the Ridges subnet is not enough: you must LOCK it.** Credits accrue only from *locked* stake. Ridgeline shows both your stake and your locked stake separately, and provides a sample lock command. ### Lock your stake with btcli Lock alpha you have staked on the Ridges subnet (netuid 62) to a hotkey with `btcli lock add`: ```bash theme={null} btcli lock add \ --network finney \ --wallet-name \ --amount \ --netuid 62 \ --hotkey-ss58
\ --mode perpetual ``` Ridgeline prefills the target hotkey and amount in the sample command on your account page. Copy that command and replace `YOUR_WALLET` with your own wallet name. `AMOUNT` is in subnet alpha units and cannot exceed the alpha you already have staked on netuid 62. * **Locked alpha still earns staking rewards** while it is locked. * **Top up an existing lock** by running `btcli lock add` again with the same hotkey; the amount is added to what's already locked. * **Check your locks** with `btcli lock list --wallet.name WALLET_NAME --netuid 62`. **Timing:** after you lock stake, credits do not appear instantly. Disbursement runs on a cycle and the balance syncs periodically, so allow up to several hours before your credits are available. Next: [Connect a wallet](/ridgeline/connect-wallet). # Dispatch a Job Source: https://docs.ridges.ai/ridgeline/dispatch-a-job Visit the [Ridgeline dashboard (**Mission control**)](https://app.ridges.ai/dashboard) to view your jobs, each corresponding to a git issue which you input, and ultimately a pull request, which the Ridges agent outputs to your repository. Jobs are grouped by status: * **Live** (*Working now* - currently being worked on by an agent) * **Review** (*Waiting on you* - PR is open for your review) * **History** (*Completed* - the PR is no longer open, whether merged or closed) ## Job Lifecycle Describe the task. This creates a real **GitHub issue** on your connected repository. > *Example:* "Find and fix the bug that generated the logs in `mysterious-error-logs.txt`" Click **New Issue**, then **Create issue** to submit. Each dispatched job costs **1 credit**. Getting the most out of that credit is a matter of how you write the task; see [Writing good prompts](/ridgeline/writing-good-prompts). The issue remains under **Live** while the agent is working on it, until it moves to **Review**. While **Live**, a job moves through: 1. **Queued**: waiting for a slot. 2. **Preparing workspace**: setting up the sandbox. 3. **Working**: solving the task. 4. **Preparing pull request**: applying the patch and opening the PR. When that finishes with an open PR, the issue moves to **Review**. Open the PR in GitHub or from the link in the job page to review the agent's changes. When the PR is merged or otherwise closed, the job moves to **History** (*Completed*). ## Rerun with context If a result comes back as a partial success, try [Rerun with context](/ridgeline/dispatch-a-job#rerun-with-context) to refine it rather than opening a fresh issue. The rerun will keep the conversation history from the earlier attempt together with your feedback, additions, or amendments. Each re-run job also costs **1 credit**. # Ridgeline FAQ Source: https://docs.ridges.ai/ridgeline/faq ## Is it safe to give Ridgeline access to my GitHub account? Ridgeline uses a GitHub App installation, so you pick exactly which repositories it can access, GitHub enforces that boundary, and you can revoke access at any time from your GitHub settings. The agent that works your job runs in a sandbox with no credentials, and its only output is a pull request for you to review. That said, your code does leave your machine: it is cloned into the job sandbox, portions of it are sent to model inference providers (with explicit controls to not use for training), and your job history (including patches) is stored by Ridges. In keeping with the general [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), you should connect selected repositories rather than your whole account. Read about [Ridgeline's Privacy and Security model](/ridgeline/privacy-and-security). ## Can miners see my data or access my repositories? No. The miner submitted the agent code to a competition, but the miner does not run it and receives no data or access related to your job or repository or account. Your job runs the agent inside a sandbox on Ridges infrastructure: its inputs are your task and your repository, its only outputs are the patch and job comments that go to you, and its only network access is model inference through a platform controlled proxy. There is no channel that carries anything back to the agent's author. Miners never see which jobs their agent ran, let alone the contents. ## Can Ridges engineers see my code? We cannot see any of your code that isn't already public. The platform has access via a GitHub App that only sees repos you install it on, using short-lived installation tokens the service mints to run jobs. See [Privacy and Security](/ridgeline/privacy-and-security). ## Who actually runs the model inference? Third party model providers, reached through the Ridges inference gateway. The [gateway code is open source](https://github.com/ridgesai/ridges) and supports OpenRouter, which routes to commercial model providers. Portions of your code are included in inference prompts, so whoever serves a request can see that content while processing it. The platform enforces a no logging policy on the inference accounts it controls in the evaluation harness, and the exact provider mix used for Ridgeline jobs is operator configuration. ## Do I need cryptocurrency to use Ridgeline? No. You can subscribe with a regular payment card, or you can earn credits by locking alpha stake on the Ridges subnet if you already hold it. See [Get credits](/ridgeline/credits) for both options. A Bittensor wallet is only needed for the staking route. ## How much does a job cost? One credit per dispatched job, regardless of size. A rerun of an existing job also costs one credit. There is no per token billing. See [Dispatch a job](/ridgeline/dispatch-a-job). ## I locked stake but my credits have not appeared. Is something broken? Credits from locked stake are disbursed on a cycle and the balance syncs periodically, so there is a delay of up to several hours between locking and seeing credits. Also confirm that you actually **locked** the stake rather than merely holding it; only locked stake accrues credits. See [Get credits](/ridgeline/credits). # Building Software with Ridgeline Source: https://docs.ridges.ai/ridgeline/getting-started Ridgeline lets you solve problems with our state-of-the-art coding agent derived from the Ridges competitions. Ridgeline is designed as an end-to-end software engineering agent, rather than as an interactive assistant. Provide a complete specification of the desired result, and the agent computes the code solution from a securely isolated compute environment, and opens a pull request on your GitHub repo just like a human developer would. One pull request costs one credit. ## The Ridgeline Agent Pipeline: The agent works unattended, in a sandbox managed by Ridges.AI. The Ridgeline agent delivers a pull request to your repo, which can only be merged with your approval. The full flow depends on two inputs you provide: the issue brief you write, and your repository itself, i.e. whether it can be installed and tested from a clean checkout. See [Ridgeline: Writing Good Prompts](/ridgeline/writing-good-prompts). The agent executes the following lifecycle for each job/issue you submit: 1. **Sets up the environment** from what is in the repository, installing dependencies with a standard command. 2. **Runs your test suite before changing anything**, to record a baseline. Failures already present are treated as out of scope, unless the failure is the exact behavior your task describes. 3. **Reads your brief and turns it into a spec.** The issue text is the whole task description. The agent expands it into a working specification grounded in your repository's structure, then plans the change from that. It cannot come back to ask a follow up question, so what you wrote is all it has. 4. **Makes the change.** 5. **Runs your code again to check its own work**, at the cheapest level that gives real confidence: the narrowest test that covers the change first, the broader suite at most once at the end. The bar is simple: nothing that passed before the change may fail after it. 6. **Reviews its own diff** against your brief and that spec. A separate review pass flags unrelated file changes, leftover debug output, scaffolding, and broken references. Cleanup issues are fixed, and a patch that misses part of the task is sent back for another attempt, before anything reaches you. 7. **Opens a pull request** for you to review. ## Usage Overview Sign in and connect a repository. Start with a low stakes repo until you know what to expect. See [Connect GitHub](/ridgeline/connect-github). Read [Privacy and Security](/ridgeline/privacy-and-security) for what Ridgeline can and cannot do with your GitHub access. Either subscribe with cash (fiat) payments, or earn credits by locking stake on the Ridges Bittensor subnet. See [Get credits](/ridgeline/credits). One job costs one credit. Open an issue describing the work. The agent runs it and opens a PR. See [Dispatch a job](/ridgeline/dispatch-a-job). One clear and complete task description beats many small ones. See [Writing good prompts](/ridgeline/writing-good-prompts). # Privacy and Security Source: https://docs.ridges.ai/ridgeline/privacy-and-security Connecting an AI agent to your GitHub account is a real trust decision. This page explains exactly what Ridgeline can and cannot do with that access, where your code travels, and how to limit your exposure. This is an engineering description, not a legal document; the [Terms of Service and Privacy Policy](https://app.ridges.ai/legal) govern your use of the platform. ## How GitHub access works Ridgeline cannot log in as you and does not receive your GitHub password or a personal access token. Instead, you install the [Ridges AI GitHub App](https://github.com/apps/ridges-ai) on your account or organization. When the Ridges agent needs to do something, it requests short-lived, specific-purpose credentials from GitHub, which expire on their own and are managed by the GitHub backend, never by the agent working on your code or by your browser session. GitHub Apps have three properties that matter here: 1. **You choose the repositories.** At install time, GitHub asks whether the app may access all repositories or only ones you select. Ridgeline only ever sees the repositories you grant. 2. **Permissions are scoped and enforced by GitHub.** The app operates under the specific permission set shown on the install screen, not under your full account authority. It cannot change your account settings, manage your other apps, or act outside the granted permissions. 3. **You can revoke access at any time.** Go to [github.com/settings/installations](https://github.com/settings/installations), open the Ridges AI app, and remove repositories or uninstall it entirely. Revocation takes effect immediately. The app requests the following permissions on the repositories you grant. This list comes from GitHub's public app manifest ([api.github.com/apps/ridges-ai](https://api.github.com/apps/ridges-ai)), so you can check it yourself at any time: | Permission | Access | Why Ridgeline needs it | | ------------- | -------------- | --------------------------------------------------------- | | Contents | Read and write | Clone your repository and push the agent's branch | | Issues | Read and write | Create and comment on the issue that represents your job | | Pull requests | Read and write | Open the pull request containing the agent's patch | | Workflows | Read and write | Push patches that modify files under `.github/workflows` | | Metadata | Read | Basic repository information; required by all GitHub Apps | The app also subscribes to the `issues`, `pull_request`, and `repository` webhook events, which is how the platform tracks the state of jobs and pull requests. The **Workflows** permission means an agent patch can modify your GitHub Actions configuration. Depending on your repository's triggers, workflows may run on the agent's branch, with access to repository secrets, before you review the pull request. Review any changes under `.github/workflows` with particular care, and avoid connecting repositories whose CI holds sensitive secrets. ## What the agent can and cannot do The agent that works your job runs inside an isolated sandbox container. The contract between the platform and the agent is narrow, and it is the same contract used to evaluate agents in the Ridges competition (see [the agent contract](/guides/agent-contract)): * **Input:** the task description you wrote, plus a checkout of the connected repository mounted inside the container. * **Output:** a patch (a unified diff). Nothing else the agent produces leaves the sandbox. * **No credentials:** the agent's environment contains no GitHub token, no account identity, and no platform secrets. The platform applies the agent's patch, pushes the branch, and opens the pull request itself, outside the sandbox. The practical consequence: the agent can read everything in the repository you connected, and its only way to affect the world is the pull request you review. It cannot push to repositories you did not connect, cannot merge its own pull requests, cannot delete branches or repositories, and cannot touch anything else on your GitHub account. ## Where your code goes Granting repository access means your code is processed outside your machine. Be aware of three data flows: 1. **The sandbox.** Your repository is cloned into an isolated container for the duration of the job. 2. **Model inference.** The agent solves your task by calling large language models through the Ridges inference gateway. Portions of your code are included in those prompts. Inference is served by third party providers, including decentralized GPU networks on Bittensor. 3. **Job history.** Ridgeline stores your job records, including the task text, the agent's summaries, and the full patch, so you can review past work in the dashboard. This history lives on Ridges servers. The [Privacy Policy](https://app.ridges.ai/legal) states that information is kept as long as necessary to provide the service and that you can contact Ridges to request deletion. ## What is open and what is not Ridges is unusually inspectable for an AI coding product. The evaluation harness is open source in the [ridges repository](https://github.com/ridgesai/ridges), and much of the agent code competing on the platform is published for anyone to read, run, and audit. Agent code is published when an agent is unseated from the leaderboard; the current top agents are kept private while they lead. The Ridgeline product backend, which holds the GitHub App credentials and orchestrates jobs, is not open source. Its handling of tokens and stored data is a matter of trusting the Ridges team rather than something you can independently verify. ## Recommendations * **Install the app on selected repositories only.** Avoid choosing "all repositories" unless intended. Grant access one repository at a time, as you need it. * **Treat pull request review as your security boundary.** Read the diff before merging, exactly as you would for a human contributor you have not worked with before. * **Revoke access when you stop using the product.** Uninstalling the GitHub App at [github.com/settings/installations](https://github.com/settings/installations) cuts off all repository access immediately. If you have questions this page does not answer, ask in the [Ridges Discord](https://discord.gg/WTsCZpdHQ). # Writing Good Prompts Source: https://docs.ridges.ai/ridgeline/writing-good-prompts Ridgeline is an end-to-end coding agent, and does not need to be managed interactively. It costs one credit per job. Write detailed acceptance criteria for the end result you want, rather than attempting to managing the agent through a process step-by-step, as you might with another code assistant. The agent is set up to work in **Python**: its sandbox comes with Python and a broad library set, so it installs your dependencies and runs your test suite. It is directed to stick to Python — for other stacks (Node, Go, Rust, and the like) it will not install a toolchain or run your suite, and instead verifies with lighter checks such as confirming the code compiles. So while it can read, reason about, and edit any codebase, don't count on it running a non-Python suite today. The advice below matters most, and pays off most, for a repo it can run. Ridgeline is built for making changes to a codebase. It will pull a reference or install a lightweight package when a coding job calls for it, but it is not a research or data-gathering tool — broad, open-ended jobs that aren't really about code tend to spend a job's budget without landing a clean result. Scope your prompt to the coding change you want. Your prompt is the whole brief. The agent's first move is to expand what you wrote into a working spec — reading your repository's structure to ground it — and then it runs unattended, with no way to come back and ask a follow-up. So describe the outcome you want clearly and completely, and let it work out the *how*. Because the whole job hinges on that written brief, it is worth drafting and sharpening it wherever you write most clearly, then dispatching the polished version. ## Practice Test-Driven Development A Ridgeline agent does not just read your repository; it runs inside a container with your code mounted, and it can compile files, run scripts, and execute test, then read the results and act on them. It works on a feedback loop, rather than emitting a single guess, provided you have set up your repo to be easy to work with. Give Ridgeline a definition of success that it can verify. State the end result as acceptance criteria that can be encapsulated as tests. Two patterns work well: * Write the tests yourself and ask for the code that makes them pass. * Describe the features in detail, ask for a test suite that covers the specification, then ask for the implementation that satisfies it. ## Provide context and constraints * **Documentation**: If your project has a test command, name it. If it needs setup, say so. This lets the agent close the loop efficiently instead of guessing at your conventions. * **Point to the relevant files or modules** if you know where the work belongs. It saves the agent from searching and keeps the change scoped. * **State the constraints** that matter: public APIs that must not change, libraries to prefer or avoid, performance or style requirements. * **Say whether it is a fix or a feature.** A fix should be a minimal, backward-compatible change to existing behavior; the agent will keep it targeted and avoid new files. A feature is built end-to-end, so give it acceptance criteria and expect the agent to build the behavior first and its tests second. * **Scope the job.** One well-defined change per job produces a cleaner result than a broad, open-ended ask. Split large efforts into separate jobs. * **Artifacts**: When squashing a bug or doing root cause analysis, give the agent everything it needs to reproduce the failure, if possible, and any error messages, logs, or detailed descriptions of the events around the failure. A bug the agent can reproduce is a bug it can confirm it has fixed. ## Take advantage of the agent's code execution capabilities Ridgeline does not just write a change and hand it to you unverified. The agent runs inside a container with your repository mounted, and it can **execute your code**: install dependencies, run scripts, and invoke your test suite. Before it delivers a PR, it can confirm that its change actually does what you asked, on your code, in your environment. There is a catch, and it is the whole point of this page. **The agent can only validate what your repo lets it run.** If your tests pass from a clean checkout, the agent can prove its fix works. If your tests need an undocumented environment variable, a database nobody mentions, or a manual setup step buried in someone's head, the agent hits the same wall a new hire would, and it falls back to weaker signals like "the code compiles." A repo that is easy for a new engineer to run is a repo the agent can validate. The setup below is worth doing once, and it pays off on every job. ## Give it a test command that works from a clean checkout The single highest-leverage thing you can do is make your tests runnable in one documented command from a fresh clone. That is what turns "the agent thinks this is right" into "the agent ran your suite and it passed." * Document the command plainly: `pytest` (or `python manage.py test`). A non-Python command like `npm test` or `go test ./...` documents intent, but the agent sticks to Python and won't run it today — see the note at the top of this page. * Make sure it passes on `main` before you dispatch a job. Ridgeline runs your suite to record a baseline *before* it changes anything, and treats every failure already present as out of scope — so a bug hiding behind a test that is red on `main` will be read as pre-existing and left alone, unless that failure is the exact behavior your task describes. * If setup is needed first, script it: `make setup && make test`, not a paragraph of prose. ## Make dependencies installable without a human The agent installs your dependencies itself before it starts, running a standard install (`pip install -r requirements.txt`, `pip install -e ".[test]"`). Keep that install boring so it succeeds on its own: standard, lightweight, pip-installable Python packages. Heavy or unusual toolchains may not install, and it cannot reach your **private** services or secrets or ask you for a credential mid-run — its environment has to be reconstructable from what is in the repo. * Declare dev/test dependencies (e.g. a `[test]` extra) so the suite's requirements come with them, and install with a standard command the agent can find and run. * Pin dependencies in a lockfile (`requirements.txt`, `pyproject.toml`) for a reproducible install. * Keep dependencies lightweight and standard — the agent is built to fetch ordinary Python packages, not to stand up heavy or exotic toolchains. * Avoid tests that reach out to your private or live third-party services. Stub or mock them. ## Remove hidden setup Anything the agent needs but cannot discover from the repo is a step it will skip. * Provide example config: commit a `.env.example`, and default sensibly when a value is missing. * If a test needs a service like a database, start it as part of the test command (for example a `make test-integration` target that spins one up), rather than assuming it is already running. * Ship seed data and fixtures the tests depend on. ## Keep the feedback loop fast Every job has a time budget. A suite that takes forty minutes leaves the agent no room to run it, read the result, and iterate. It will run a smaller slice or skip verification entirely. * Keep the core suite fast, or expose a quick subset the agent can target. * Make failures readable. Clear assertion messages tell the agent exactly what broke. ## Expose the other checks you rely on If your definition of "good" includes more than tests, make those runnable too, so the agent can hold itself to the same bar you would. * A lint command: `ruff check`, `eslint`, `golangci-lint`. * A type check: `mypy`, `tsc --noEmit`. * A build step, if a passing build is part of done. ## Ask for validation in your prompt Once the repo supports it, tell the agent to use it. Name the command and state the bar. * "Run `npm test` and make sure the full suite passes before finishing." * "Add a test that reproduces the reported bug, confirm it fails, then fix it and confirm it passes." # Pay with x402 Source: https://docs.ridges.ai/ridgeline/x402 Ridgeline accepts onchain micropayments through the [x402 protocol](https://www.x402.org/). Purchase a single credit at a time, at the moment you dispatch a task. x402 is one of three ways to fund Ridgeline work. You can also, [get credits](/ridgeline/credits) through a monthly subscription, or earn them by locking alpha stake on the Ridges subnet. **1 payment** -> **1 credit** -> **1 GitHub Issue** -> **1 Pull Request** ## How to dispatch a job with x402 **Requirements**: * The [Ridgeline GitHub App](https://github.com/apps/ridges-ai/installations/new) installed on the target repository. * A wallet holding USDC on Base. It must be a wallet you hold the private key for yourself (for example, exported from MetaMask), not a hosted or custodial account. Send `POST https://product.ridges.ai/v1/issues` with the URL of a GitHub issue on a repository where the Ridgeline GitHub App is installed: ```json theme={null} { "github_issue_url": "https://github.com/owner/repo/issues/123" } ``` With no payment attached, the response is an HTTP `402 Payment Required` challenge. The payment terms (amount, USDC asset, receiving address, network) come back in the `PAYMENT-REQUIRED` response header. Your wallet signs the payment payload and retries the same request with the signed payment in the `X-PAYMENT` request header. The facilitator verifies the signature, then settles the transfer onchain. You are only ever charged once settlement fully completes. The moment settlement confirms, the task starts. There are no credits to track and no second step: the response returns your `issue_id`, and the onchain transaction hash comes back in the `X-PAYMENT-RESPONSE` header. The Ridgeline agent works the issue and opens a pull request, same as any other plan. If a payment settles but the task fails to start (for example, a server error after settlement), do not assume the money is lost: the payment is recorded server side. Do not retry the request, as you may be charged again. Contact support with the transaction hash. ## What is x402? HTTP has reserved status code `402 Payment Required` since the 1990s, but the web never standardized what it should actually do. x402 is an open protocol, initiated by Coinbase, that finally puts it to work: 1. A client requests a paid resource with a normal HTTP request. 2. Instead of the resource, the server replies `402 Payment Required`, with exact payment terms attached in a header that machines can read: the amount, the asset, and the address to pay. 3. The client's wallet signs a payment authorization matching those terms and retries the same request with the signed payment attached. 4. A third party called a **facilitator** verifies the signature and settles the payment onchain. Once the money moves, the server delivers the resource in that same response. The whole exchange is just HTTP plus a stablecoin transfer. There is no signup, no credit card form, no API key, and no invoice. Because every step is readable and executable by a machine, a software agent can pay for a service entirely on its own, which is exactly the use case Ridgeline cares about: an autonomous agent that hits a problem it wants Ridgeline to solve can purchase exactly one task, mid run, without a human in the loop. Ridgeline's x402 payments settle in **USDC** (a dollar pegged stablecoin) on **Base** (an Ethereum layer 2 with very low transaction fees), verified and settled through a Coinbase facilitator. ### Learn more * [x402 protocol site](https://www.x402.org/) * [x402 on GitHub](https://github.com/coinbase/x402) # Architecture Source: https://docs.ridges.ai/ridges/architecture ## System Architecture Ridges operates on an open source agent competition platform where miners both compete and collaborate on a software engineering agent. This is made possible by four core components that together create a robust evaluation ecosystem: Agent developers who submit code-solving AI systems for competitive evaluation Evaluates agents and gives them a score to rank Central coordination service managing agent submissions, evaluation orchestration, communication and publication of agent code. ## The Flow Validators pull submitted code and run it on benchmark problems, evaluating the output. Emissions are split among every approved agent in proportion to how much it improved on the best agent at the time it was approved. See the [incentive mechanism](/incentive-mechanism) for how that split is calculated. 1. Miners create an agent and publish it to the Ridges Platform. 2. The agent enters a screening pipeline (Screener 1 → Screener 2 → Validators). At each stage it runs against a set of problems in an isolated sandbox. 3. Validators score the agent and report results to the platform. 4. The platform decides whether the agent qualifies for emissions, assigns it a reward score, and sets on-chain weights across all qualifying agents. 5. Agent code is published when an agent is unseated from the leaderboard, for others to study, run, and build on. The current top agents are kept private while they lead. ## Network Topology ```mermaid theme={null} graph TB M[Miners] --> API[Platform API] API --> S[Screeners] S --> V[Validators] S --> SSB[Sandboxes] V --> VSB[Sandboxes] API --> DB[(Database)] API --> S3[S3 Storage] V --> BC[Blockchain] style M fill:#1976d2,color:#ffffff style V fill:#7b1fa2,color:#ffffff style S fill:#f57c00,color:#ffffff style API fill:#388e3c,color:#ffffff style SSB fill:#455a64,color:#ffffff style VSB fill:#455a64,color:#ffffff ``` # The Ridges Way Source: https://docs.ridges.ai/ridges/ridges-way Models can already generate good code, but they currently lack the intelligence to do the many component steps that are also part of a SWE (software engineers) role. Eventually, instead of an engineer interacting continuously with a coding assistant to check every detail, they should be able to submit an entire problem specification and be able to reliably know that it will be completed for them. Ridges challenges AI agents to face an infinite, evolving gauntlet of difficult, well-defined, coding problems. Ridges is built on the principles of trustless verification and yielding reproducible performance claims through end-to-end control of the experimental environment. Agents run in a sandbox with no network access except metered inference, against hidden, randomized problem sets organized into [niche competitions](/competitions/overview), with a [pre-screening judge](/guides/miner-faq) that rejects agents that hardcode benchmark behavior or target verifier details, and [consensus scoring](/scoring) across independent validators. Every evaluated agent's code is open-sourced for anyone to run once it is no longer earning emissions for actively holding a leader spot. Researchers at University of Pennsylvania [found](https://debugml.github.io/cheating-agents/) that agents do their most impactful cheating on benchmarks at the harness level, by having answers leaked into their execution environment through the submitter's scaffold. That problem is eliminated on Ridges by design, as a miner submits only one artifact, the agent file. The execution harness, the container, the environment, and the verifier invocation are screened off from miner access and normalized to produce a sterile test environment. Closed agents may also take the shortcut of hardcoding known solutions. Ridges removes that most basic of cheating strategies structurally: * **The problems are hidden and randomized.** Miners do not know which problems they will be evaluated on, and per problem inference seeds reduce variance gaming. * **The screening process hunts for gaming.** Agents that appear to hardcode behavior, probe verifier internals, or game the process are rejected before they consume validator capacity, and [participation rules](/participation-rules) ban them. * **The agent code is inspectable.** The exact `agent.py` that earned the score is open-sourced once the agent is no longer earning emissions for actively holding a leader spot. Reuse of published agent code is governed by the [Ridges.AI Terms of Service](https://app.ridges.ai/legal): code is published for inspection, for verifying the platform's claims, and for building better agents on the platform. # Screeners and Validators Source: https://docs.ridges.ai/ridges/screeners-and-validators Submitted agents pass through a three-stage evaluation pipeline before earning emissions. Each stage runs your agent against a set of problems in an isolated sandbox and scores the output. ## Pipeline overview | Stage | Problems | Pass threshold to advance | | --------------- | -------- | ------------------------- | | Screener 1 | 20 | 45% | | Screener 2 | 20 | 60% | | Validators (×3) | 50 each | — | Screener 1 and Screener 2 have mutually exclusive problem sets. Validators draw from a combined pool. The problem counts and pass thresholds above are from Competition 23 and may vary per competition. Check the current competition details on the [Ridges dashboard](https://www.ridges.ai/agents) for the latest values. The platform computes a **consensus score** across validators: for each problem, the agent receives credit only if every assigned validator marks it solved. That consensus score is what the [incentive mechanism](/incentive-mechanism) compares against the current leader to decide whether the agent qualifies for emissions and how large a share it receives. Weight is set on-chain via `subtensor.set_weights()` and Yuma Consensus determines the resulting emissions. See: * [Incentive Mechanism](/incentive-mechanism) * [Bittensor Docs: Yuma Consensus](https://docs.learnbittensor.org/learn/yuma-consensus) * [Bittensor Docs: Emissions](https://docs.learnbittensor.org/learn/emissions) ## Problem types and Scoring Each competition draws its problems from its [niche](/competitions/overview) (linting, database query engineering, etc.), using the InfiniteSWE generation pipeline. Scoring is deterministic: 0–1, the fraction of hidden test cases your patch passes. There is no model judge and no code quality rubric. A patch either passes a test or it doesn't. Test names, test logs, and inference details are hidden from miners during and after evaluation. You can see your overall score, inference cost, and runtime — not individual test outcomes. ## How screeners run Ridges runs a pool of screeners that scales with demand — more instances spin up when submissions surge and scale back down when the queue clears. Screening is the pipeline's main throughput bottleneck, so it carries the brunt of any spike. When you submit an agent: 1. Your agent code is downloaded from platform storage 2. An isolated Docker container is created per problem 3. The agent runs and produces a patch 4. The patch is applied and the hidden test suite runs 5. Pass/fail results are aggregated into a final score If a run fails due to a platform error (not your agent), it is re-run automatically. Most submissions stop here: screening filters out lower-quality agents before they ever consume validator capacity, so only a minority of submitted agents reach the validator stage. ## Shared capacity across competitions When more than one [competition](/competitions/overview) is running, screeners and validators are **shared** across all of them and rotate between the competitions that need work, rather than each competition holding its own dedicated pool. At busy times a competition may be waiting on capacity that is currently working another. The competition page on the dashboard shows which connected validators are running in that competition, which are running in other competitions, and which are idle. Most of the time capacity is ample. ## How validators run Validators operate the same way as screeners but are run by independent validator nodes on the network, not hosted by Ridges. Agents that pass Screener 2 are evaluated by three validators independently. For the validator leaderboard, a problem counts only when every assigned validator marks that problem solved for the agent. The final score is the fraction of validator problems that meet that consensus rule. ## What miners can see After a run completes, you can view: * Overall score per stage * Inference cost and runtime for each problem * Comparison against the competition average You cannot see test names, test output, or which specific problems you passed or failed. # Roadmap Source: https://docs.ridges.ai/roadmap Ridges is evolving the best software-engineering agents in the world, using a decentralized adversarial evaluation network. This page tracks major milestones and what's coming next. ## Q4 2024 * **Launch as AgenTao:** The subnet launched on Bittensor as AgenTao (SN62), introducing autonomous software engineering agents competing to solve code problems for emissions. ## Q3 2025 * **Open source state of the art:** Ridges agents reached state-of-the-art performance among open-source SWE-bench agents. * **Validator rewrite:** The validator stack was rewritten to reduce evaluation time and make new top agents possible on a much faster cadence. * **Agent-code publication policy:** Agent code is published when an agent is unseated from the leaderboard, preserving transparency while keeping active submissions and the current top agents private. ## Q4 2025 * **Polyglot benchmarks:** Polyglot benchmarks added multi-language implementation tasks alongside SWE-bench-style repository repairs. ## Q1 2026 * **Latent acquisition:** Latent acquired Ridges, increasing engineering capacity for the platform, & bringing specialized Bittensor knowledge. * **Inference infrastructure expansion:** Ridges expanded model and provider support, added streaming support for inference, and added OpenRouter as a supported provider. * **Ridgeline beta:** Ridgeline launched in beta with a Jira-style task board for assigning software-engineering work to agents. ## Q2 2026 * **Ridgeline workflow controls:** Ridgeline added reruns with extra context, stop controls, collapsible run history, and per-run commit statistics. Improving overall UX of the product. * **Miner-owned inference economics:** Evaluations moved toward miner-owned inference keys. Evaluation cost is charged directly to the miner's provider account, increasing cost efficiency of the agents as a result. * **Harbor integration live:** Ridges integrated Harbor by Terminal Bench for benchmark execution, improving support for more languages, more complex tasks, and a cleaner patch-then-verify evaluation contract. * **New upload and evaluation flow:** Introduced the miner CLI, local testing, and randomized hidden problems, improving local-to-production parity while reducing overfitting risk. * **Hardcoding pre-screening judge:** Pre-screening judge introduced for agents that appear to hardcode benchmark behavior, target verifier details, or game the evaluation process. Agents flagged by pre-screening are rejected before consuming validator capacity. * **Consensus validator scoring:** Problem credit became stricter: a problem only counts as solved when all assigned validators agree on the result. This reduced scoring variance and makes rankings harder to win. * **Fixed inference budget:** Each evaluation run received a fixed inference budget. This made cost a first-class constraint and pushed miners to optimize for quality under a known spend cap. * **Faster evaluation pipeline:** Score-bound cancellation introduced along with earlier screener exits, parallel screener execution, validator parallelization, and cost-based tie breakers to improve throughput and reduce wasted evaluation work. * **Auto-approval system:** Auto-approval went live for agents that meet approval criteria and pass safety checks to gain emissions. The approval pipeline uses up to three judge-backed review rounds for consensus. * **Evaluation integrity and scale improvements:** Per-problem inference seeds, faster pre-screening, resilient uploads, detailed validator statistics, and capacity upgrades rolled out for variance reduction and faster evaluations. Expanded the per-submission evaluation set to 90 problems across the full pipeline (Screener 1 → Screener 2 → Validator), giving agents a broader, harder path to approval. * **Introduction to InfiniteSWE problems:** Miners got exposed to synthetic benchmarks for the first time in their problem set; problems which are actual engineering issues with clear deterministic pass & failure criteria. ## Q3 2026 * **Proportional incentive mechanism:** Emissions moved from a single top agent to qualifying approved agents, with shares determined by decaying reward scores. Both performance gains and cost reductions can qualify an agent, and improvements that break longer stalemates earn larger rewards. See the [incentive mechanism](/incentive-mechanism). * **Coldkey ban mechanism:** Agents belonging to banned coldkeys are excluded from leader selection and from emissions. * **Introducing Niches:** Introduced specialized competitions for agents with a single hyperfocus, with curated tasks across real application repositories and languages including Python, Go, and TypeScript. Each niche has tailored judging policies that reward transferable engineering skills and distinguish legitimate specialization from knowledge of specific benchmark tasks. See [Competitions and Niches](/competitions/overview). * **Multi-competition support:** Enabled multiple competitions to run concurrently, each with its own leaderboard, scoring and approval policies, and share of subnet emissions. Validators and screeners share evaluation capacity across competitions, allowing different engineering niches to develop alongside one another. * **Real application environments:** Tasks can now run multiple containers with live services such as PostgreSQL, ClickHouse, and Redis etc. Agents work against real databases and application dependencies, enabling evaluation of query correctness, data behavior, and performance across complete service stacks. * **Isolated verification:** Upgraded to Harbor 0.20 with support for separate agent and verifier environments. Tasks and the verifier environment are completely isolated to the OS level - hardening the security layer even more. * **Ridgeline x402 and MCP:** Launched x402 payments and an MCP integration so autonomous agents can submit GitHub issues to Ridgeline, pay for work programmatically, and delegate implementation through their existing tools. See [Pay with x402](/ridgeline/x402). * **Scalable evaluation infrastructure:** Expanded Kubernetes execution with autoscaling, improved image builds and caching, and automatic retries for transient infrastructure failures. These upgrades support larger task environments and concurrent competition workloads. ## In progress * **Ridgeline GitHub workflows:** Expanding GitHub integration for shared repositories, with branch selection, clearer progress reporting, and more reliable execution from issue to pull request. * **Ridgeline agent improvements:** Developing Ridgeline's agent to bring together specialists for different engineering tasks, improving the quality and reliability of its work. * **Targeted Niche expansion:** Expanding Niches around the engineering skills Ridgeline needs, so subnet competitions develop specialists that directly improve the product. * **Introduction of new categories & offerings:** Stay tuned # Scoring Source: https://docs.ridges.ai/scoring Scoring is **deterministic**: agents submit a patch, the platform applies the diff and runs the hidden test suite, and the score is the fraction of tests that pass (0–1). No model judge, no code quality rubric. The evaluation pipeline for a submitted agent: | Stage | Problems | Pass threshold | | --------------- | -------- | -------------- | | Screener 1 | 20 | 45% | | Screener 2 | 20 | 60% | | Validators (×3) | 50 each | — | Screeners use the verifier results for their stage thresholds. At the validator stage, the platform computes a consensus score: for each problem, the agent gets credit only if every assigned validator marks that problem solved. Scoring produces the score. Turning scores into weight is the job of the [incentive mechanism](/incentive-mechanism): emissions are divided among all approved agents in proportion to how much each improved on the leader when it was approved. Weight is set on-chain via `subtensor.set_weights()`, and Yuma Consensus determines the resulting emissions. See: * [Bittensor Docs: Yuma Consensus](https://docs.learnbittensor.org/learn/yuma-consensus) * [Bittensor Docs: Emissions](https://docs.learnbittensor.org/learn/emissions) ## Scoring is per competition Problems now belong to a [competition's niche](/competitions/overview): a focused skill such as linting or database query engineering, with a problem set built and mutated for it. Each competition carries its own scoring and approval policy, so screening thresholds, problem counts, and approval bars will differ between niches. ## Why test names and logs are hidden Miners previously hardcoded agents to pass known specific tests. To prevent this, Ridges hides test names, test logs, and inference results from miners during and after evaluation. You can see your score, your inference cost, and your runtime, but not the individual test outcomes.