WorkspaceGuard
About
MCP server wrapping the WorkspaceGuard CLI for workspace usage checks.
Details
- Author
- rudrendupaul
- Categories
- Developer Tools
Jump to
Setup
Install WorkspaceGuard in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/rudrendupaul/WorkspaceGuard
Follow the installation instructions in the repository README, then restart your MCP client.
What is WorkspaceGuard, and why does it exist
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.
WorkspaceGuard 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 doesn't provide: usage metering and quota enforcement per workspace.
Free tier (this repo, MIT):per-workspace message counting, monthly cap enforcement, a CLI/JSON usage report.Not in this repo:a hosted, multi-tenant billing dashboard is a separate, closed-source product, mentioned here only as a roadmap item and never merged into this MIT codebase.
- src/core/isolation-guard.ts-- the single choke point (chat()) every request flows through: resolve workspace, check quota, call backend, record usage.
- src/core/usage.ts-- the usage-metering engine this project adds: per-workspace, per-month counters with automatic period rollover, andQuotaExceededErrorenforcement.
- src/core/vault.ts,src/core/namespace.ts,src/core/circuit-breaker.ts-- the original isolation-engine code, kept as the identity and workspace-boundary substrate the metering layer reads from.
- src/adapters/-- theBackendAdapterinterface.MockAdapteris the only implementation today; a real Odysseus HTTP adapter has not been built yet.
Backend-specific behavior never enterssrc/core/directly. Everything goes throughBackendAdapter.
WorkspaceGuard trusts an upstream identity header (default:Cf-Access-Authenticated-User-Email) to resolve the workspace.
[!WARNING] This service must never be directly reachable from the network. Only run it behind a trusted proxy that sets that header (Cloudflare Access, Tailscale, etc.). This boundary is documented, not code-enforced.
- Real and tested:usage metering, quota enforcement, the original isolation engine (vault, namespace separation, circuit breaker), and the CLI with--jsonmode, verified by 41/41 passing TypeScript tests and 50/50 passing Python tests.
- Not yet built:a real Odysseus HTTP adapter (onlyMockAdapterexists today) and a hosted, multi-tenant billing dashboard (deliberately out of scope for this MIT repo).
- docs/getting-started.md
- docs/concepts.md
- docs/integrations/ci.md
- docs/integrations/backends.md
Q: What does WorkspaceGuard actually do?A: It adds per-workspace usage metering and quota enforcement in front of one shared self-hosted AI assistant deployment. It counts messages per workspace per month, lets you set an optional cap that fails closed once hit, and gives you (or an agent) aworkspaceguard usagereport. It does not add chat history, memory, or API key isolation itself; that already exists by default in the target platform (see "What is WorkspaceGuard" above), and WorkspaceGuard's own isolation code (src/core/vault.ts,src/core/namespace.ts) is kept only as the identity-resolution substrate the metering layer reads from.
Q: What's WorkspaceGuard's actual differentiator?A: Narrow scope done well: not a full billing platform, and not a reimplementation of isolation the backend already has. Every request flows through one choke point (chat()insrc/core/isolation-guard.ts), quota enforcement fails closed on a corrupted usage store instead of silently resetting everyone's usage to zero (seeCHANGELOG.md), and every command supports--jsonfor agent-native output.
Q: How does WorkspaceGuard compare to Odysseus?A: It isn't a competing product. WorkspaceGuard is a sidecar that sits in front of an Odysseus deployment (or a compatible backend); it doesn't replace anything Odysseus already does. See thecomparison tableabove for the specific capability split.
Q: What platforms does WorkspaceGuard run on?A: The npm package (workspaceguard-cli) requires Node.js 20 or newer (engines.nodeinpackage.json). The Python port inpython/requires Python 3.9 through 3.13 (see the classifiers inpython/pyproject.toml). Neither distribution ships a platform-specific binary, so both run wherever their respective runtime does (Linux, macOS, Windows).
Q: Is WorkspaceGuard a CLI, a library, or both?A: Both, in both distributions. The CLI (workspaceguard <command>) coversinit,add-workspace,status,usage,set-cap,rotate-key, andscan. The same functionality is importable directly (createWorkspaceGuardfrom the TypeScript package,create_workspace_guardfrom the Python package) for anything that wants to call it from code instead of shelling out.
Q: What's a real current limitation I should know about before relying on this?A: The only backend adapter implemented today isMockAdapter, an in-memory adapter used for tests and local experimentation. A real Odysseus HTTP adapter has not been built yet (seedocs/integrations/backends.md), so WorkspaceGuard does not yet forward live chat traffic to an actual Odysseus deployment. The metering and quota logic itself is real and tested; the network bridge to a live backend is the piece still outstanding.
Q: Does WorkspaceGuard need its own API keys, or hold any of my AI provider credentials?A: No. The only backend adapter that exists right now (MockAdapter) is in-memory and calls no external API. All backend-specific behavior is isolated behind theBackendAdapterinterface (src/adapters/), so WorkspaceGuard's own code never needs to see provider credentials directly.
Q: Is WorkspaceGuard free to use commercially?A: Yes. This repository is MIT licensed in full, with no dual licensing and no feature gate. The hosted, multi-tenant billing dashboard mentioned above is a separate, closed-source product described only as a roadmap item; no billing-dashboard code lives in, or is withheld from, this MIT codebase.
SeeCONTRIBUTING.mdandSECURITY.md. Notable changes are tracked inCHANGELOG.md.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Create crafted UI components inspired by the best 21st.dev design engineers.
Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server
An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .
MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent
ALAPI MCP Tools,Call hundreds of API interfaces via MCP
AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform
MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.
APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.
One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.
Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
