workspaceguard-cli (Python)

Per-workspace usage metering and quota caps for one shared self-hosted AI assistant deployment -- a genuine, independent Python port of the workspaceguard-cli npm package, not a wrapper around a Node binary.

Why this exists

Run Odysseus (or a compatible self-hosted assistant) for your whole household or small team, and there is 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 thin sidecar that adds that layer: per-workspace message counts, optional monthly caps that fail closed, and a CLI report an admin (or another agent) can read.

This project originally set out to add per-user workspace isolation (separate chat history, memory, API keys) to a self-hosted AI chat platform. A feasibility spike found that Odysseus already enforces per-user ownership on chat history, memory, and API tokens by default, so building a competing isolation layer would have duplicated work Odysseus already does correctly. This project instead keeps its tested isolation engine (namespace separation, an AES-256-GCM vault with real key rotation, fail-closed identity resolution, a self-healing circuit breaker) as the identity-resolution substrate, and builds the layer Odysseus does not provide: usage metering and quota enforcement per workspace. See the project README for the full story.

Install

pip install workspaceguard-cli

Current status: this Python port is fully built, tested (50/50 pytest tests passing), and published to PyPI. pip install workspaceguard-cli works today -- see pypi.org/project/workspaceguard-cli. The npm package (workspaceguard-cli) is also published and installable today via npm install -g workspaceguard-cli -- see npmjs.com/package/workspaceguard-cli. This package is a genuine, independent port -- not a wrapper around the npm package -- so it works and is maintained regardless of the npm package's status.

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

$ workspaceguard usage --json
{"ok": true, "usage": [{"workspaceId": "alex", "identity": "alex@example.com", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-07", "messageCount": 0, "estimatedBytes": 0}]}

CLI reference

Every command accepts --json for a structured, agent-native output shape instead of the human-readable text shown below. Identical command surface to the npm CLI.

Global options

Data directory resolution, in order: --data-dir flag, then WORKSPACEGUARD_DATA_DIR env var, then ~/.workspaceguard. This used to default to the current working directory with no override -- running init from the wrong shell could silently write a live encryption key into an unrelated directory. init on an existing, valid key is idempotent (it loads and reuses that key); init on a key file that exists but doesn't decode to a valid key refuses to overwrite it without --force.

Known issue on the currently published 0.1.2 release: the -h/--help and -V/--version rows above describe the fixed, not-yet-published behavior. workspaceguard-cli==0.1.2 (the version live on PyPI today) does not implement those two flags; running either one falls through to the default unknown-command path and exits with status 1. Every other command in this table works as documented on 0.1.2. See CHANGELOG.md for the fix and its publish status.

Library API

import asyncio
from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError

async def main():
    guard = await create_workspace_guard(data_dir="./data", backend=MockAdapter())
    await guard.add_workspace("alex", "alex@example.com")
    await guard.set_cap("alex", 1000)

    try:
        await guard.chat("alex@example.com", "hello")
    except QuotaExceededError:
        pass  # alex is over their monthly cap

    report = await guard.usage_report()

asyncio.run(main())

The library API is async (asyncio), matching the async architecture of the original TypeScript source rather than flattening it to synchronous calls.

How it works

target: an inbound chat request with an identity header value
   -> resolve_workspace() -- fail closed on any miss, never a default workspace
   -> check_quota() -- QuotaExceededError if the workspace is at its cap
   -> circuit breaker -- calls the BackendAdapter, opens after 3 consecutive
      failures, self-heals via a half-open probe after a cooldown
   -> record usage -- per-workspace, per-month counters with automatic
      period rollover

• workspaceguard/isolation_guard.py -- the single choke point (chat()) every request flows through: resolve workspace -> check quota -> call backend -> record usage.
• workspaceguard/usage.py -- the usage-metering engine this project adds: per-workspace, per-month counters with automatic period rollover, and QuotaExceededError enforcement.
• workspaceguard/vault.py, workspaceguard/namespace.py, workspaceguard/circuit_breaker.py -- the original isolation-engine code, kept as the identity/workspace-boundary substrate the metering layer reads from, not shipped as a competing isolation product.
• workspaceguard/adapters/ -- BackendAdapter abstract base class; a real Odysseus HTTP adapter is the next step (currently MockAdapter only, same as the TypeScript original).

Backend-specific behavior never enters the core modules directly -- everything goes through BackendAdapter.

Trust boundary

WorkspaceGuard trusts an upstream identity header (default: Cf-Access-Authenticated-User-Email) to resolve the workspace. It must never be directly reachable from the network -- only from behind whatever trusted proxy sets that header (Cloudflare Access, Tailscale, etc.). This is documented, not code-enforced.

What's real vs. not yet built

• Real, tested (50/50 pytest tests passing): usage metering, quota enforcement, the original isolation engine (vault, namespace separation, circuit breaker), CLI with --json mode.
• Not yet built: a real Odysseus HTTP adapter (only MockAdapter exists so far, same as the TypeScript original), a hosted managed billing dashboard (deliberately out of scope for this MIT project).

Security

The vault uses AES-256-GCM (via the cryptography package) with one derived key per workspace per generation -- rotating a workspace's key increments its generation, so old ciphertext genuinely can no longer be decrypted, not a no-op. See SECURITY.md for the disclosure process and what's in/out of scope.

Contributing

See CONTRIBUTING.md.

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT, see LICENSE.