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 success, instead of staying tripped forever.
• One choke point, not scattered checks. chat() in src/core/isolation-guard.ts is the single place every request flows through: resolve workspace, check quota, call backend, record usage.
• Two independent, tested distributions. The TypeScript package (npm) and the Python port (PyPI) implement the same design against separate test suites: 41/41 TypeScript tests and 50/50 Python tests passing as of this writing.

CLI reference

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

Global options

[!WARNING] --force permanently invalidates anything already encrypted under the old master key. Only use it when the existing key file is confirmed unrecoverable.

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.

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

The --json mode is what makes this agent-native rather than just human-convenient: an orchestrator or monitoring agent can call workspaceguard usage --json and parse the result directly instead of scraping terminal output.

Library API

import { createWorkspaceGuard, MockAdapter, QuotaExceededError } from "workspaceguard-cli";

const guard = await createWorkspaceGuard({ dataDir: "./data", backend: new MockAdapter() });
await guard.addWorkspace("alex", "alex@example.com");
await guard.setCap("alex", 1000);

try {
  await guard.chat("alex@example.com", "hello");
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // alex is over their monthly cap
  }
}

const report = await guard.usageReport();

The Python port exposes the same shape: from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError.

MCP Server

WorkspaceGuard's Python distribution ships a Model Context Protocol server, so an MCP-compatible agent (Claude Desktop, Claude Code, an orchestrator) can call WorkspaceGuard directly as a tool instead of shelling out to the CLI and parsing text.

pip install "workspaceguard-cli[mcp]"

It exposes one tool, run, a generic subprocess wrapper: pass it the same argument list you'd pass on the command line, and it shells out to the installed workspaceguard binary, parses the resulting JSON, and returns it. Every failure mode (missing binary, launch error, timeout, non-zero exit, unparseable output) comes back as a plain {"error": ...} dict instead of raising, so a bad call can't crash the server.

run(args=["usage", "--json"])
# -> {"ok": true, "usage": [{"workspaceId": "alex", "identity": "alex@example.com", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-08", "messageCount": 0, "estimatedBytes": 0}]}

To register it with an MCP-compatible client such as Claude Desktop, add it to the client's server config:

{
  "mcpServers": {
    "workspaceguard": {
      "command": "workspaceguard-mcp"
    }
  }
}

This assumes workspaceguard-mcp is already on PATH (installed via the mcp extra above). If you installed it somewhere else, replace "command" with the full path to the console script.

Comparison

WorkspaceGuard is a sidecar, not a competing product. It sits in front of an Odysseus deployment (or a compatible backend) and adds the one layer that backend doesn't provide.

What is WorkspaceGuard, and why does it exist

Read the full README on GitHub →