The Quota Cliff: A Failover Pattern for When Your Free Agent Server Runs Dry

The Saturday that ended on Sunday

A small team — three developers, one shared codebase — spent a weekend building a proof of concept. The setup was simple: a coding agent running on MonkeyCode's free server, a ten-million-token allowance, and a backlog of small refactoring tasks.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant that currently offers free model access and a free server option with a ten-million-token allowance.

Saturday went well. The agent handled thirty-seven tasks, mostly renames and test stubs. The team merged everything by midnight.

Sunday morning, the first task failed. Then every task failed. The quota was gone — not because anyone was careless, but because one batch refactor consumed more than the sum of all the small tasks. The allowance had looked generous on paper. It was gone by noon.

The team had two options: wait for the reset, or scramble to set up a local model. They chose the second and lost three hours to installation and configuration. The momentum was gone.

This article is about the pattern that would have saved that weekend: a quota guard that watches the allowance and flips the workflow to a fallback backend before the cliff arrives.

Free quotas are a capacity plan, not a gift

A free allowance is a finite resource with a hard ceiling. Treating it as unlimited is the root cause of most quota crashes. The fix is not to avoid the free tier. The fix is to design for the moment it runs out.

The pattern has three parts:

1. A monitor that tracks token consumption against the allowance.
2. A threshold that triggers the switch early, while there is still budget left.
3. A fallback backend that can absorb the remaining work at lower quality or higher latency.

The goal is not to prevent exhaustion. The goal is to make exhaustion invisible.

Part 1: The monitor

The monitor reads the current usage and compares it with the allowance. In production, this would call a real usage endpoint. For the pattern, a local JSON file works as a stand-in.

{
  "used_tokens": 8200000,
  "limit_tokens": 10000000
}

#!/usr/bin/env python3
"""quota_guard.py — watch the allowance and flip the router before the cliff."""
import json
import os
import time

QUOTA_FILE = os.environ.get("QUOTA_FILE", "usage.json")
ROUTER_FILE = os.environ.get("ROUTER_FILE", "router.json")
THRESHOLD_PCT = float(os.environ.get("THRESHOLD_PCT", "80"))

def load_usage():
    with open(QUOTA_FILE) as fh:
        return json.load(fh)

def switch_route(mode):
    config = {
        "mode": mode,
        "switched_at": time.time(),
    }
    with open(ROUTER_FILE, "w") as fh:
        json.dump(config, fh, indent=2)
    print(f"[quota_guard] router switched to {mode}")

def main():
    usage = load_usage()
    used = usage.get("used_tokens", 0)
    limit = usage.get("limit_tokens", 1)
    pct = (used / limit) * 100
    print(f"[quota_guard] {used} / {limit} tokens ({pct:.1f}%)")

    if pct >= THRESHOLD_PCT:
        switch_route("fallback")
    else:
        switch_route("primary")

if __name__ == "__main__":
    main()

The threshold of 80 percent is a starting point, not a rule. A workload with large, unpredictable batch jobs needs a lower threshold. A workload with small, steady tasks can push higher.

Part 2: The router

The router reads the current mode and dispatches each task to the right backend. The configuration lives in a separate file, so the switch does not require a code change.

{
  "mode": "primary",
  "primary": {
    "type": "managed_free",
    "endpoint": "https://api.monkeycode.example/v1",
    "note": "free server with 10M token allowance"
  },
  "fallback": {
    "type": "local",
    "endpoint": "http://localhost:11434",
    "model": "local-coder:latest",
    "note": "no quota, slower on large refactors"
  }
}

#!/usr/bin/env python3
"""route.py — dispatch a prompt to the active backend."""
import json
import subprocess
import sys

def load_router():
    with open("router.json") as fh:
        return json.load(fh)

def run_primary(prompt):
    print("[route] primary -> managed free server")
    # Replace with the actual CLI invocation for your backend.
    return subprocess.run(["monkeycode", "run", prompt], capture_output=True, text=True)

def run_fallback(prompt):
    print("[route] fallback -> local model")
    # Replace with the actual CLI invocation for your local model.
    return subprocess.run(["ollama", "run", "local-coder:latest", prompt], capture_output=True, text=True)

def main():
    router = load_router()
    prompt = sys.argv[1]
    result = run_fallback(prompt) if router.get("mode") == "fallback" else run_primary(prompt)
    print(result.stdout)
    if result.returncode != 0:
        print(result.stderr, file=sys.stderr)
        sys.exit(result.returncode)

if __name__ == "__main__":
    main()

The fallback model is a placeholder. Any local model with a compatible CLI works. The important part is that the fallback exists and is tested before the cliff, not after.

Part 3: The schedule

The monitor needs to run regularly. A cron entry every ten minutes is a reasonable default:

*/10 * * * * cd /path/to/project && python3 quota_guard.py

Ten minutes is a compromise. A shorter interval catches spikes faster but adds noise. A longer interval risks crossing the cliff between checks.

What the pattern does not solve

The quota guard has real limits.

Quality drops. A local fallback model is not the same model. Simple tasks — renames, boilerplate, test stubs — will be fine. Complex refactors may produce worse results or fail entirely. The guard switches the backend, not the quality bar.

Monitoring lag. The usage file is only as fresh as the last update. If the agent CLI writes usage data lazily, the guard can be blind to a sudden spike. The team that lost its quota on Sunday hit exactly this case: one batch task consumed the remaining twenty percent between two checks.

Setup cost. The fallback backend must exist before the cliff. Installing a local model after the quota is gone is the exact scramble this pattern is meant to avoid.

Who should not use this pattern

The quota guard fits small teams and weekend projects. It does not fit everyone.

• Production CI pipelines that need consistent model quality should pay for a reliable backend, not degrade silently.
• Teams with strict data boundaries should skip the managed free server entirely and run a local model from day one.
• Interactive editor completions need sub-second latency. A shared managed server and a local fallback both fail this test; this pattern does not fix that.

The takeaway

A free allowance is a finite resource. The teams that treat it as one — with a monitor, a threshold, and a fallback — never notice the cliff. The teams that do not, lose a Sunday.

If the pattern fits your workflow, copy the scripts, set the threshold, and test the fallback before you need it. The ten minutes it takes will save you the weekend.