Subscription Credentials
Share Claude Max/Pro subscription tokens across multiple agents, with automatic assignment, health monitoring, and auto-switch on rate limits.
Watch
All videosTrinity Platform Demo
May 2026
Concepts
•Subscription — A Claude Max or Pro subscription token registered with Trinity. Stored encrypted (AES-256-GCM). Injected as an environment variable to assigned agents.
•Round-Robin Assignment — New agents automatically get a subscription assigned. The subscription with the fewest agents is selected first, with alphabetical tie-break.
•Auto-Switch — When an agent hits a rate-limit (429) or auth-class failure, Trinity automatically switches it to a different subscription. The new token is applied via a hot-reload of the running container — no container recreate — so in-flight executions keep running. Default ON; toggle it off in the Subscriptions section of Settings.
•Hot-Reload Rotation — Manual token changes hot-reload the same way: re-registering a subscription with a fresh token pushes the new token to every running agent on that subscription, and reassigning an agent from one subscription to another swaps the token in place. In-flight turns finish on the old token; the next turn uses the new one. Container recreation is only needed for image, template, or auth-mode changes (e.g. switching between subscription and API key).
How It Works
1
Go to the Settings page.
2
In the Subscriptions section, click Register Subscription.
3
Enter a subscription name and token.
4
The subscription is encrypted and stored.
5
Expand a subscription row to see assigned agents with assign/unassign controls.
6
New agents auto-assign via round-robin.
Encryption Requirement
•
CREDENTIAL_ENCRYPTION_KEY must be set in .env. This is auto-generated by start.sh on fresh deployments.•If missing: a warning banner appears on the Settings page, the Register button is disabled, and the API returns 503.
•Check status:
GET /api/subscriptions/encryption-statusHealth Monitoring
•Subscription credential health is monitored continuously.
•Auto-remediation triggers on failures.
•Alerts fire on degraded subscriptions.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/subscriptions | GET | List all subscriptions |
| /api/subscriptions | POST | Register a subscription |
| /api/subscriptions/{id} | DELETE | Delete a subscription |
| /api/subscriptions/{id}/assign | POST | Assign to an agent |
| /api/subscriptions/{id}/unassign | POST | Unassign from an agent |
| /api/subscriptions/encryption-status | GET | Check encryption key status |
MCP Tools
•
register_subscription(name, token) — Register a new subscription.•
list_subscriptions() — List all subscriptions and their assigned agents.•
assign_subscription(subscription_id, agent_name) — Assign a subscription to an agent.•
clear_agent_subscription(agent_name) — Remove subscription assignment from an agent.•
get_agent_auth(agent_name) — Get the auth configuration for an agent.•
delete_subscription(subscription_id) — Delete a subscription.Limitations
•Requires
CREDENTIAL_ENCRYPTION_KEY in .env. Without it, subscription features are unavailable.•Auto-switch depends on failure detection. If an agent does not surface 429 or auth-class errors through standard logging, auto-switch will not trigger.
•Hot-reload applies the new token to the next Claude subprocess; turns already in flight finish on the previous token. On older agent base images that lack the hot-reload endpoint, the switch falls back to recreating the container (which drops in-flight executions).
•Round-robin assignment considers only agent count, not agent activity or usage volume.
•An API key in
.env will not override a subscription. On a Claude-runtime agent authenticated by a subscription, Trinity strips ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN from the execution environment before each run. Claude prefers an API key over the subscription token, so a stale one left on the agent's workspace volume would silently authenticate every run — and its failures would be blamed on the subscription, marking healthy subscriptions unhealthy in turn. If you genuinely want an agent on an API key, clear its subscription rather than putting a key in .env. Agents on other runtimes are unaffected. GET /api/credentials/status reports which keys are being suppressed, by name.