OpenGlass

A neutral witness for agent-to-agent interactions. See docs/SPEC.md and CLAUDE.md.

Run locally

docker compose up --build -d --wait
curl -k https://localhost/health     # {"status":"ok","checks":{"mongo":"ok","s3":"ok"}}

Caddy serves https://localhost with a certificate from its internal CA. -k skips verification. To trust the CA instead:

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
curl --cacert caddy-root.crt https://localhost/health

MinIO no longer publishes official images, so compose uses the maintained community build pgsty/minio, pinned to a release.

See it in action

examples/witnessed-negotiation is a runnable, end-to-end demo: two agents register, get claimed, negotiate a purchase order over a witnessed session, close it, and independently verify the resulting record — against the real API, not a mock. See examples/README.md.

Risk policy

/spec/openglass-policy is a small, versioned, vendor-neutral YAML format for classifying an agent's action as low/medium/high risk — deciding when an action is worth a witnessed record, separate from the attestation mechanism itself (docs/SPEC.md §12). Reference evaluators: core-js (@openglass/core) and core-py (openglass-core), kept in sync by a shared set of test vectors. See docs/POLICY.md for the guide.

Integrations

otel-js/otel-py (openglass-otel) plug into an already-OpenTelemetry-instrumented agent: a SpanProcessor reads GenAI spans, classifies each against an openglass-policy, and opens an attestation for the risky ones — no OpenGlass-specific code in the agent itself. See examples/otel-integration for a runnable demo. langchain-py (openglass-langchain) does the same for LangChain tool calls via a BaseCallbackHandler — see examples/langchain-integration. /integrations/_template is the starting point for a new framework-specific integration, including the conformance tests every integration must pass.

The public /integrations page is the request board: a card per framework (from a static catalog, apps/api/data/integrations.yaml), voting and a request form (gated on the existing owner login, not GitHub OAuth — see the PR that added this for why), and an admin view at /integrations/admin to update status. Admin access needs the ADMIN_EMAILS env var set (comma-separated owner emails) — nobody is an admin until it is.

scripts/adoption-review.ts is a runnable report over that board's live data (vote leaderboard, the 3 frameworks to prioritize next, new requests) — run it yourself or from your own cron, whenever you want it, rather than it running unattended:

node --experimental-strip-types scripts/adoption-review.ts
# optionally: OG_ADMIN_SESSION_COOKIE="og_session=..." to include the request queue (admin-only)

Develop and test

corepack enable
pnpm install
pnpm -r build
pnpm -r typecheck
pnpm -r test          # starts a throwaway mongo:7 container (needs Docker)

Same tests, different MongoDB

The database is configured by MONGODB_URI and nothing else. With MONGODB_URI unset, the tests start a throwaway mongo:7 container. With it set, they run against that server instead. Each test file uses its own og_test_<random> database and drops its collections afterwards.

# the local compose Mongo
MONGODB_URI='mongodb://localhost:27017/openglass?directConnection=true' pnpm -r test

# an Atlas free-tier cluster: only the URI changes
MONGODB_URI='mongodb+srv://<user>:<password>@<cluster>.mongodb.net/openglass?retryWrites=true&w=majority' pnpm -r test

For the Atlas run:

• The database user needs readWriteAnyDatabase and dbAdminAnyDatabase. Tests create per-file databases, and migrate runs collMod to set validators.
• Your IP must be on the cluster's access list.

The production app user only needs readWrite and dbAdmin on the openglass database.

Schema changes

• Collections are defined in packages/db/src/models. Each has a Zod model, a $jsonSchema validator generated from that model, and named indexes. migrate applies all of them idempotently on api start, under a lock.
• Data changes go in versioned scripts: pnpm --filter @openglass/db migration:create <name>, which writes to packages/db/migrations.

Deploy

main is built, pushed to ECR and deployed to a single EC2 instance by .github/workflows/deploy.yml. The AWS resources and first-time setup are in infra/README.md.