lwhfxmoss/sub2api-oauth-sleeper-plugin

★ 18PythonAudience · ops devopsComplexity · 3/5ActiveSetup · moderate

Mindmap

mindmap
  root((sub2api-oauth-sleeper))
    Inputs
      Sub2API accounts table
      Usage percent fields
      Reset timestamps
    Outputs
      rate_limited_at column
      rate_limit_reset_at column
      Plugin event log
    Use Cases
      Sleep saturated OAuth accounts
      Protect Codex 5h and 7d windows
      Track Anthropic session windows
    Tech Stack
      Python
      PostgreSQL
      Docker
      Docker Compose

mindmap root((sub2api-oauth-sleeper)) Inputs Sub2API accounts table Usage percent fields Reset timestamps Outputs rate_limited_at column rate_limit_reset_at column Plugin event log Use Cases Sleep saturated OAuth accounts Protect Codex 5h and 7d windows Track Anthropic session windows Tech Stack Python PostgreSQL Docker Docker Compose

Things people build with this

USE CASE 1

Run as a sidecar next to an existing Sub2API deployment so OAuth accounts are paused before they hit hard rate limits.

USE CASE 2

Centralise sleep policy for OpenAI Codex 5-hour and 7-day windows across many pooled OAuth accounts.

USE CASE 3

Mirror Anthropic session-window and 7-day passive usage into the rate-limit fields Sub2API already understands.

USE CASE 4

Audit when and why accounts were put to sleep via the plugin event log table.

Tech stack

PythonPostgreSQLDockerDockerCompose

Getting it running

Difficulty · moderate Time to first run · 1h+

You must collect the real Sub2API Postgres credentials and Docker network by hand before writing .env, and put auth in front of the admin page because it ships unauthenticated.

In plain English

This project is a small add-on for a service called Sub2API, which manages OAuth accounts that are used to call AI providers like OpenAI and Anthropic. Those provider accounts have usage windows, for example a five-hour limit and a seven-day limit, and once a window is close to full the account should stop being used until the window resets. The plugin watches those numbers and proactively marks an account as rate-limited in the Sub2API database before requests start failing. The README is careful to say what the plugin is and is not. It runs as a sidecar container next to an existing Sub2API deployment and talks only to the same PostgreSQL database that Sub2API already uses. It does not call any OpenAI, Anthropic, or Sub2API admin APIs, does not change the Sub2API source code or schema, and does not need OpenAI or Anthropic API keys. The fields it writes are two existing columns on the accounts table, rate_limited_at and rate_limit_reset_at, plus two new tables that store the plugin's own settings and event log. For OpenAI OAuth accounts it reads percentages and reset times for the 5-hour and 7-day Codex windows out of an extra JSON column. For Anthropic OAuth accounts it reads session window and 7-day passive usage figures from the same place, multiplying them by 100 because Anthropic stores them as fractions. When a usage percent is at or above the configured threshold and the reset time is still in the future, the account is put to sleep until the later of the matching reset times. The author is direct about security. The open-source build exposes its admin page and API without any built-in login, which fits a private LAN or VPN deployment but is dangerous on the public internet, since anyone who reaches the page can mark Sub2API accounts as rate-limited. The README recommends putting Basic Auth, SSO, or firewall rules in front of the plugin and never exposing it openly. A large portion of the document is written specifically for an AI agent doing the deployment. It lists hard rules (do not restart the main Sub2API or PostgreSQL containers, do not change the schema, do not expose unauthenticated), the values the agent must collect from docker ps and docker inspect rather than guess, the shape of the .env file to generate, and a verification checklist for after the container is running.

Copy-paste prompts

Prompt 1

Write a docker-compose.override.yml that joins the sub2api-oauth-sleeper-plugin to my existing sub2api_default network and points DATABASE_URL at the sub2api-postgres service.

Prompt 2

Generate a Caddyfile snippet that puts Basic Auth in front of PUBLIC_BASE_PATH=/custom/oauth-sleeper and forwards to the plugin container on port 8080.

Prompt 3

Given my Sub2API accounts.extra schema, write a SQL query that lists all OAuth accounts where codex_5h_used_percent is above 90 but rate_limited_at is still NULL.

Prompt 4

Produce a runbook for safely turning on the plugin against a production Sub2API database, including a test Postgres validation step and how to disable any duplicate scanner.

Prompt 5

Add a Prometheus metrics endpoint to this plugin that exposes the count of accounts asleep per platform and the last scan timestamp.

Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.