Hylon Admin Runbook

Overview

Everything tunable about Hylon lives in two places, both adjustable at runtime with no redeploy:

• credit_config rows (key/value): the free-tier allowance, warning threshold, and node point rates.
• hylon_model_pricing rows: per-model credit rates.

All endpoints on this page require an admin JWT (Authorization: Bearer with an admin role) and are mounted under /api/v1/admin. Responses use the standard { "success": true, "data": { } } envelope.

Config knobs (credit_config)

These are the hylon_* keys the code reads today, stored as plain strings in credit_config (config_key / config_value columns). A missing key falls back to the registry default, so deleting a row is safe. GET /api/v1/admin/hylon/config is authoritative: its entries array enumerates the whole registry merged over whatever rows exist, with each key's type, default, description, and bounds.

Billing

Node program point awards

Economy: points→ORB bridge (default CLOSED)

Economy: earning lanes

Daily point caps by lane; a negative value means uncapped. These bound the earning rate only and never gate AI access.

Economy: Season Clearing

Notes:

• Seeds only INSERT when the key is absent, so values you change are never reverted by a redeploy or container restart.
• Rate changes take effect immediately for new requests and new task verifications; they never rewrite history.
• A negative point rate is treated as 0 at award time.
• Every write is validated against the registry (type + bounds), applied in one transaction (all-or-nothing), and recorded in the audit log.

Billing config endpoints

curl https://api.orbai.world/api/v1/admin/hylon/config \
  -H "Authorization: Bearer <ADMIN_JWT>"

{
  "success": true,
  "data": {
    "config": {
      "free_daily_tokens": 100000,
      "low_balance_warning_credits": 500
    },
    "entries": [
      {
        "key": "hylon_points_bridge_enabled",
        "value": "false",
        "default": "false",
        "type": "bool",
        "known": true,
        "description": "Hylon economy: master gate for the points->ORB bridge (default closed; points-before-token)"
      }
    ],
    "pricing": [
      {
        "model": "Qwen/Qwen2.5-3B-Instruct",
        "input_credits_per_mtok": 20,
        "output_credits_per_mtok": 60,
        "cached_input_credits_per_mtok": 0,
        "is_active": true
      }
    ]
  }
}

entries is the complete, self-describing knob list (sorted by key) and is what the admin UI renders. config remains for the two legacy billing fields.

# Legacy shorthand: halve the free allowance
curl -X PUT https://api.orbai.world/api/v1/admin/hylon/config \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"free_daily_tokens": 50000}'

# Generic form: tune any hylon_* knob (all-or-nothing, audited)
curl -X PUT https://api.orbai.world/api/v1/admin/hylon/config \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"set": {"hylon_lane_attested_daily_cap": 300, "hylon_lane_paid_tenure_days": 45}}'

Node program fleet ops

curl https://api.orbai.world/api/v1/admin/hylon/nodes \
  -H "Authorization: Bearer <ADMIN_JWT>"

{
  "success": true,
  "data": {
    "nodes": [
      {
        "id": 8,
        "name": "my-mac",
        "owner_user_id": 22468,
        "device_type": "desktop",
        "deployment_type": "HOME",
        "tier": "server",
        "status": "online",
        "last_seen": "2026-07-28T10:00:00Z",
        "points": 6,
        "tasks_reported": 6,
        "tasks_verified": 6,
        "contributions": {
          "tasks_completed": 6,
          "compute_units": 0,
          "inference_requests": 0
        }
      }
    ],
    "task_counts": { "queued": 4, "leased": 2, "completed": 6 },
    "queue_depth": 4,
    "total_points_awarded": 6,
    "program_status": "beta"
  }
}

Reading the fleet view:

• status is online only when the node checked in within the last 5 minutes; disabled reflects a deactivated node record.
• A wide gap between tasks_reported and tasks_verified on one node means its completions are failing server-side re-verification. That is the cheat signal; verified counts are the only ones that ever award points.
• task_counts is keyed by task status: queued, leased, completed, failed, unsupported, or expired.
• queue_depth is the number of queued tasks. The lease path self-replenishes with up to 10 verify.recompute tasks when a node finds the queue empty, so an empty queue is not an outage.

# Seed 50 benchmark tasks
curl -X POST https://api.orbai.world/api/v1/admin/hylon/nodes/enqueue \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"kind": "bench.cpu", "count": 50}'

bench.cpu tasks are only created by this endpoint (the auto-top-up mints verify.recompute only), so benchmark availability is entirely an operator decision.

Season ops (Season Clearing)

A season is the accounting window contributor rewards clear against. Its budget is banked from real service revenue, so rewards behave like a dividend rather than an emission: at settle time every earner is paid pro-rata out of a budget that already exists.

The lifecycle is open → closed → settled. Points are stamped with the open season at award time; only one season may be open at a time. Settlement records what each contributor cleared but credits no ORB — crediting happens only through the separately gated points→ORB bridge, so the points-before-token rule holds end to end.

curl -X POST https://api.orbai.world/api/v1/admin/hylon/seasons \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Season 1", "banked_revenue_usd": 5000, "points_orb_rate": 10}'

# Typical end-of-season sequence
curl -X POST .../seasons/3/close  -H "Authorization: Bearer <ADMIN_JWT>"
curl -X POST .../seasons/3/settle -H "Authorization: Bearer <ADMIN_JWT>"

The settled rate is min(budget_orb / total_points, season rate cap, hylon_season_max_points_orb_rate) where budget_orb = banked_revenue_usd × hylon_orb_per_usd, so a season can never clear more value than it banked. Re-running settle is a no-op; a settled season is immutable.

Operational notes

• Free-tier accounting rolls up per user per UTC day; the cap check runs inside the settlement transaction, so raising or lowering the allowance mid-day applies to the next request.
• Settlement shortfalls: usage ingest settles what the account can cover and floors at zero rather than dropping a served request. A shortfall is recorded in the usage event metadata (shortfall_credits) for reconciliation. Watch for repeated shortfalls from one account.
• Idempotency everywhere: usage settlement is idempotent per request_id; task points are awarded at most once per task; setup codes are single use. Re-sending a request never double-charges or double-awards.
• Credit isolation: hylon_credit_balance is a dedicated pool. No admin action on VPN wallets, ORB balances, or scan credits touches it, and vice versa.
• Payments: a completed Stripe payment for a product='hylon' plan grants the Hylon subscription through the payment pipeline's Hylon branch. OrbVPN payment behavior is untouched by any of it.