WorkspaceGuard

Install • Quickstart • CLI Reference • Comparison • FAQ

Per-workspace usage metering and fail-closed quota caps for one shared self-hosted AI assistant deployment (Odysseus or a compatible backend).

Run Odysseus (or a compatible self-hosted assistant) for your household or small team and there's no way to see who sent how many messages this month, or to stop one person's usage from burning through everyone else's API budget. WorkspaceGuard is a sidecar that adds that layer: per-workspace message counts, an optional monthly cap that fails closed, and a CLI (or JSON) report an admin or another agent can read.

npx workspaceguard-cli usage
-> alex   [alex@example.com]: 812 messages this period, cap 1000 (81%)
-> jordan [jordan@example.com]: 203 messages this period, cap unlimited

Install

npm install -g workspaceguard-cli

Or run it without installing:

npx workspaceguard-cli usage

The package is workspaceguard-cli; the command it installs is workspaceguard. A genuine, independent Python port with the same CLI surface and --json shapes is published separately as workspaceguard-cli on PyPI (pip install workspaceguard-cli, see python/).

Quickstart

# Register the workspaces sharing one deployment (identity = the header value
# your reverse proxy sets after authenticating, e.g. Cloudflare Access).
workspaceguard add-workspace alex --identity alex@example.com
workspaceguard add-workspace jordan --identity jordan@example.com

# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
workspaceguard set-cap alex 1000

# See usage for every workspace.
workspaceguard usage

Real output from a fresh install:

-> alex [alex@example.com]: 0 messages this period, cap 1000 (0%)
-> jordan [jordan@example.com]: 0 messages this period, cap unlimited

Features

• Per-workspace message counting. Every request through the sidecar's chat() entry point increments a per-workspace, per-month counter (src/core/usage.ts), isolated so one workspace's usage never leaks into another's.
• Quota enforcement that fails closed. A workspace at its cap gets a QuotaExceededError before the backend is ever called. If the usage store is corrupted or unreadable, WorkspaceGuard blocks requests instead of silently resetting everyone's count to zero (see CHANGELOG.md).
• Agent-native --json on every command. workspaceguard usage --json returns structured output an orchestrator can parse directly, no screen-scraping.
• AES-256-GCM vault with real key rotation. workspaceguard rotate-key <id> re-encrypts a workspace's secrets under a new key and invalidates the old ciphertext.
• A self-healing circuit breaker. Backend calls open the circuit after 3 consecutive failures, then retry through a half-open probe and close again on succ

... View full README on GitHub