README
¶
Speakeasy AI Control Plane
Securely scale AI usage across your organization. Built for humans and agents.
Learn more »
Documentation · Running locally · Tech Stack · Contributing · Login · Roadmap
Introduction
Gram is the open source stack behind Speakeasy's AI control plane. Secure and centrally manage MCPs, Skills, and Assistants your whole company to access, with fine-grained permissions, threat detection, and full observability of token use and costs. Every tool call, permission change, and access event logged and searchable. SOC 2 Type II and ISO 27001 certified.
To get started on the hosted platform you can Sign up, or check out the Quickstart guide.
Supports popular AI providers
Observe
Track AI usage across teams and measure impact with either tokens or cost. Deep dive expensive sessions, create budgets and measure tool effectiveness. Built on a foundation of Opentelemetry. Exportable and interactive via platform MCP and a built in assistant.
Secure
Every prompt, response, and agent action is inspected and enforced in real time. Sensitive data is blocked, redacted, or logged before it leaves your environment. Create and enforce flexible policies to prevent prompt injection, log shadow use and detect PII secrets and other sensitive data types.
Connect
A single control layer for connecting your agents to MCPs for your SaaS vendors, APIs, and internal systems, with policy enforcement and granular access control built in. Private networking and tunneling deployed on demand.
Distribute
Centralise distribution of MCPs, Skills, Plugins and Assistants to your team based on enterprise roles. Team, server, and tool level permissions enforced through RBAC and Oauth2.1. Synced to your enterprise IDP (Okta, Azure AD, Google Workspace, etc.).
Support
- Chat with us: Join our slack for support and discussions or email us at support@speakeasy.com.
- Contribute feature requests or report issues on our roadmap.
- Documentation for the platform is available here.
Running locally
Run ./zero until it succeeds. This script is what you use to run the dashboard and services for local development. It installs dependencies, runs pending database migrations, and starts everything up.
The main dependencies are Mise and Docker. The ./zero script will guide you to install these if they are not found.
Once everything is running, seed the local database with sample data:
mise seed
See CONTRIBUTING.md for more detail on local development, auth, and the CLI.
Contributing
Contributions are welcome! Please open an issue or discussion for questions or suggestions before starting significant work.
See CONTRIBUTING.md for development setup and detailed contribution guidelines.
Tech Stack
- TypeScript — dashboard language.
- Golang — backend language.
- Goa — design-first API framework.
- Temporal — workflow engine.
- Polar — usage-based billing.
- OpenRouter — LLM gateway.
- Speakeasy — generated SDKs. Spec hosted here.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal/flags
Package flags defines common flags to keep CLI commands consistent.
|
Package flags defines common flags to keep CLI commands consistent. |
|
internal/profile
Package profile provides profile-based configuration management for the Gram CLI.
|
Package profile provides profile-based configuration management for the Gram CLI. |
|
Package main is the dev-idp binary entrypoint.
|
Package main is the dev-idp binary entrypoint. |
|
design
Package design declares the Goa API for the dev-idp management surface.
|
Package design declares the Goa API for the dev-idp management surface. |
|
internal/bootstrap
Package bootstrap opens dev-idp's SQLite database and applies the embedded schema on every start.
|
Package bootstrap opens dev-idp's SQLite database and applies the embedded schema on every start. |
|
internal/config
Package config parses dev-idp's runtime configuration.
|
Package config parses dev-idp's runtime configuration. |
|
internal/conv
Package conv has dev-idp's tiny set of *string <-> sql.NullString and related helpers.
|
Package conv has dev-idp's tiny set of *string <-> sql.NullString and related helpers. |
|
internal/defaultuser
Package defaultuser implements the dev-idp's "default user" bootstrap.
|
Package defaultuser implements the dev-idp's "default user" bootstrap. |
|
internal/keystore
Package keystore owns the dev-idp's single RSA keypair (idp-design.md §5.3): the only signing key the dev-idp uses, sourced from GRAM_DEVIDP_RSA_PRIVATE_KEY (PEM) at boot or freshly generated when the env var is unset.
|
Package keystore owns the dev-idp's single RSA keypair (idp-design.md §5.3): the only signing key the dev-idp uses, sourced from GRAM_DEVIDP_RSA_PRIVATE_KEY (PEM) at boot or freshly generated when the env var is unset. |
|
internal/middleware
Package middleware provides the small set of HTTP/Goa middleware dev-idp needs.
|
Package middleware provides the small set of HTTP/Goa middleware dev-idp needs. |
|
internal/modes/mockworkos
Package mockworkos implements the dev-idp's mock-workos mode — a mock WorkOS REST surface backed by the dev-idp's shared SQLite store.
|
Package mockworkos implements the dev-idp's mock-workos mode — a mock WorkOS REST surface backed by the dev-idp's shared SQLite store. |
|
internal/modes/oauth2
Package oauth2 implements the dev-idp's oauth2 mode (idp-design.md §7.4): an OAuth 2.0 authorization server with optional PKCE (honored when present), no DCR, and OIDC compliance.
|
Package oauth2 implements the dev-idp's oauth2 mode (idp-design.md §7.4): an OAuth 2.0 authorization server with optional PKCE (honored when present), no DCR, and OIDC compliance. |
|
internal/modes/oauth21
Package oauth21 implements the dev-idp's oauth2-1 mode (idp-design.md §7.3): an OAuth 2.1 authorization server with PKCE-required (S256), stateless DCR, and OIDC compliance.
|
Package oauth21 implements the dev-idp's oauth2-1 mode (idp-design.md §7.3): an OAuth 2.1 authorization server with PKCE-required (S256), stateless DCR, and OIDC compliance. |
|
internal/modes/workos
Package workos implements the dev-idp's workos mode — proxies WorkOS REST API calls to the live WorkOS dev environment.
|
Package workos implements the dev-idp's workos mode — proxies WorkOS REST API calls to the live WorkOS dev environment. |
|
internal/oops
Package oops is dev-idp's lightweight error helper.
|
Package oops is dev-idp's lightweight error helper. |
|
internal/service
Package service contains the dev-idp's Goa service implementations (organizations, users, memberships, devIdp).
|
Package service contains the dev-idp's Goa service implementations (organizations, users, memberships, devIdp). |
|
internal/workos
Package workos is dev-idp's tiny WorkOS client.
|
Package workos is dev-idp's tiny WorkOS client. |
|
pkg/devidptest
Package devidptest spins up a real dev-idp HTTP server inside a test.
|
Package devidptest spins up a real dev-idp HTTP server inside a test. |
|
pkg/testidp
Package testidp serves an in-process mock identity provider for tests.
|
Package testidp serves an in-process mock identity provider for tests. |
|
functions
|
|
|
cmd/runner
command
|
|
|
imports
Package imports provides reusable helpers for emitting analysis.TextEdit values that add or remove imports from a Go source file.
|
Package imports provides reusable helpers for emitting analysis.TextEdit values that add or remove imports from a Go source file. |
|
hooks
|
|
|
cmd/speakeasy-hooks
command
Command speakeasy-hooks is the single Speakeasy hooks binary.
|
Command speakeasy-hooks is the single Speakeasy hooks binary. |
|
relay
Package relay wires the agenthooks runtime to the Gram hooks backend.
|
Package relay wires the agenthooks runtime to the Gram hooks backend. |
|
internal/diagram
Package diagram generates a single mermaid diagram (plus text tables) that ties Gram's proto-declared Pub/Sub topology to the Go and Python call sites that publish to topics and consume subscriptions.
|
Package diagram generates a single mermaid diagram (plus text tables) that ties Gram's proto-declared Pub/Sub topology to the Go and Python call sites that publish to topics and consume subscriptions. |
|
main
command
|
|
|
Package plog provides pretty-printing for JSON lines logs with colorized output.
|
Package plog provides pretty-printing for JSON lines logs with colorized output. |
|
cmd/plog
command
Command plog pretty-prints JSON lines logs with colorized output.
|
Command plog pretty-prints JSON lines logs with colorized output. |
|
cmd/celwasm
command
|
|
|
cmd/dev-mcp
command
Command dev-mcp is a local-development MCP server that exposes assistant management operations (CRUD, running turns, triggers) over stdio.
|
Command dev-mcp is a local-development MCP server that exposes assistant management operations (CRUD, running turns, triggers) over stdio. |
|
cmd/export-hook-plugin
command
Command export-hook-plugin renders the dogfood hook plugins (plugin-claude, plugin-cursor) from the same generators that publish customer plugins.
|
Command export-hook-plugin renders the dogfood hook plugins (plugin-claude, plugin-cursor) from the same generators that publish customer plugins. |
|
cmd/gen-materialized-cols
command
|
|
|
cmd/gen-webhooks
command
Command gen-webhooks generates both catalog artifacts for the outbox events package:
|
Command gen-webhooks generates both catalog artifacts for the outbox events package: |
|
cmd/risk-pi-report
command
|
|
|
cmd/riskjudgebench
command
Command riskjudgebench benchmarks OpenRouter models for prompt-based ("LLM-judge") risk policy evaluation in the promptpolicy OpenRouter evaluator.
|
Command riskjudgebench benchmarks OpenRouter models for prompt-based ("LLM-judge") risk policy evaluation in the promptpolicy OpenRouter evaluator. |
|
cmd/tools/sweep_builtin_presets
command
Command sweep_builtin_presets is an offline operator tool that re-evaluates stored risk findings against the built-in preset false-positive catalog in the internal/risk/presetlib package and marks the known-benign noise (test credit cards, example API keys/tokens, module hashes, placeholder emails, ...) as false positives so the dashboard hides them.
|
Command sweep_builtin_presets is an offline operator tool that re-evaluates stored risk findings against the built-in preset false-positive catalog in the internal/risk/presetlib package and marks the known-benign noise (test credit cards, example API keys/tokens, module hashes, placeholder emails, ...) as false positives so the dashboard hides them. |
|
cmd/tools/sweep_false_positives
command
Command sweep_false_positives is an offline operator tool that re-evaluates stored Presidio risk findings against the false-positive catalogs in the internal/risk/presidiofp package and marks the noise (reserved IPs, placeholder emails, ...) as false positives so the dashboard hides them.
|
Command sweep_false_positives is an offline operator tool that re-evaluates stored Presidio risk findings against the false-positive catalogs in the internal/risk/presidiofp package and marks the noise (reserved IPs, placeholder emails, ...) as false positives so the dashboard hides them. |
|
design/platformadmin/remotesessions
Package remotesessions declares the adminRemoteSessions Goa service: the platform-admin (Speakeasy-only) surface for curating "global" remote_session_issuer / remote_session_client records (project_id IS NULL AND organization_id IS NULL) shared across every organization.
|
Package remotesessions declares the adminRemoteSessions Goa service: the platform-admin (Speakeasy-only) surface for curating "global" remote_session_issuer / remote_session_client records (project_id IS NULL AND organization_id IS NULL) shared across every organization. |
|
internal/auth/speakeasyclient
Package speakeasyclient is a thin HTTP client for the Speakeasy auth provider's IDP wire endpoints (`/v1/speakeasy_provider/{exchange,validate}`) plus the post-IDP user-bootstrap side effects every Speakeasy-authenticated caller should run.
|
Package speakeasyclient is a thin HTTP client for the Speakeasy auth provider's IDP wire endpoints (`/v1/speakeasy_provider/{exchange,validate}`) plus the post-IDP user-bootstrap side effects every Speakeasy-authenticated caller should run. |
|
internal/authz/repo
Package repo writes authz challenge rows to ClickHouse.
|
Package repo writes authz challenge rows to ClickHouse. |
|
internal/background/activities/outbox_relay
Package outbox_relay drains the global event outbox.
|
Package outbox_relay drains the global event outbox. |
|
internal/background/activities/risk_analysis/presidiotest
Package presidiotest provides an in-process mock of the Presidio Analyzer HTTP API.
|
Package presidiotest provides an in-process mock of the Presidio Analyzer HTTP API. |
|
internal/background/activities/risk_exclusion
Package risk_exclusion contains the Temporal activity that reconciles a risk exclusion against already-stored findings (risk_results).
|
Package risk_exclusion contains the Temporal activity that reconciles a risk exclusion against already-stored findings (risk_results). |
|
internal/cliauth
Package cliauth implements the cliAuth Goa service: the device agent's interactive enrollment via a PKCE one-time-code exchange (DNO-388).
|
Package cliauth implements the cliAuth Goa service: the device agent's interactive enrollment via a PKCE one-time-code exchange (DNO-388). |
|
internal/dns
Package dns provides a Resolver interface for DNS lookups whose method signatures match net.Resolver.
|
Package dns provides a Resolver interface for DNS lookups whose method signatures match net.Resolver. |
|
internal/email
Package email is the application-facing facade for sending transactional emails.
|
Package email is the application-facing facade for sending transactional emails. |
|
internal/externalmcptest
Package externalmcptest provides helpers for constructing externalmcp.RegistryClient instances in tests.
|
Package externalmcptest provides helpers for constructing externalmcp.RegistryClient instances in tests. |
|
internal/functionstest
Package functionstest provides helpers for constructing functions.Orchestrator instances in tests.
|
Package functionstest provides helpers for constructing functions.Orchestrator instances in tests. |
|
internal/guardian
Package guardian provides HTTP client construction with network security policy enforcement, OpenTelemetry instrumentation, resilience (rate limiting and circuit breaking), and optional retry logic.
|
Package guardian provides HTTP client construction with network security policy enforcement, OpenTelemetry instrumentation, resilience (rate limiting and circuit breaking), and optional retry logic. |
|
internal/httpcache
Package httpcache provides a shared write path for public, cacheable JSON responses.
|
Package httpcache provides a shared write path for public, cacheable JSON responses. |
|
internal/mcp/httpheaders
Package httpheaders contains shared MCP request header parsing helpers.
|
Package httpheaders contains shared MCP request header parsing helpers. |
|
internal/mcp/toolfilter
Package toolfilter is the shared home for MCP tool-filtering logic: deriving a tool's effective filter tags, applying the runtime ?tags= filter, resolving the effective variation group, and building the read-only scopes view shown on the dashboard.
|
Package toolfilter is the shared home for MCP tool-filtering logic: deriving a tool's effective filter tags, applying the runtime ?tags= filter, resolving the effective variation group, and building the read-only scopes view shown on the dashboard. |
|
internal/mcp/tunnelrouting
Package tunnelrouting selects tunnel gateway owners and handles retry policy.
|
Package tunnelrouting selects tunnel gateway owners and handles retry policy. |
|
internal/mcpservers/visibility
Package visibility declares the mcp_servers.visibility enum values.
|
Package visibility declares the mcp_servers.visibility enum values. |
|
internal/mv
Package mv, short for "model views", provides functions for rendering views over database models that can be used by other services to produce consistent representations of API resources.
|
Package mv, short for "model views", provides functions for rendering views over database models that can be used by other services to produce consistent representations of API resources. |
|
internal/oauth/wellknown
Package wellknown resolves OAuth 2.1 well-known metadata for toolsets.
|
Package wellknown resolves OAuth 2.1 well-known metadata for toolsets. |
|
internal/oauthtest
Package oauthtest provides helpers for creating OAuth-configured toolsets in tests.
|
Package oauthtest provides helpers for creating OAuth-configured toolsets in tests. |
|
internal/openapi
Workaround: Anti-Gravity rejects tool inputSchema properties that use integer enums (e.g.
|
Workaround: Anti-Gravity rejects tool inputSchema properties that use integer enums (e.g. |
|
internal/orderedmap
Package orderedmap provides a map implementation that maintains the order of keys as they are added.
|
Package orderedmap provides a map implementation that maintains the order of keys as they are added. |
|
internal/outbox
Package outbox provides the producer-side helpers for writing events to the outbox table and waking the per-org Svix relay workflow.
|
Package outbox provides the producer-side helpers for writing events to the outbox table and waking the per-org Svix relay workflow. |
|
internal/outbox/cataloggen
Package cataloggen generates server/internal/outbox/events/catalog_gen.go and server/internal/outbox/events/catalog_gen.yaml from the event definition files.
|
Package cataloggen generates server/internal/outbox/events/catalog_gen.go and server/internal/outbox/events/catalog_gen.yaml from the event definition files. |
|
internal/platformtools/memory
Package memory implements the gram://memory/* platform tools that wrap the MemoryService for use by assistant agents at runtime.
|
Package memory implements the gram://memory/* platform tools that wrap the MemoryService for use by assistant agents at runtime. |
|
internal/plugins/naming
Package naming holds the marketplace + observability-plugin name formulas shared between the plugin publish path (server/internal/plugins) and the device-agent endpoint (server/internal/agent + mv).
|
Package naming holds the marketplace + observability-plugin name formulas shared between the plugin publish path (server/internal/plugins) and the device-agent endpoint (server/internal/agent + mv). |
|
internal/ratelimit
Package ratelimit is Gram's shared token-bucket rate limiter.
|
Package ratelimit is Gram's shared token-bucket rate limiter. |
|
internal/remotemcp/interceptors
Package interceptors holds per-vendor policies applied to remote-MCP proxy traffic.
|
Package interceptors holds per-vendor policies applied to remote-MCP proxy traffic. |
|
internal/remotemcp/proxy
Package proxy forwards MCP client requests to an upstream Remote MCP Server and relays its responses back to the client.
|
Package proxy forwards MCP client requests to an upstream Remote MCP Server and relays its responses back to the client. |
|
internal/remotemcp/remotemcptest
Package remotemcptest provides helpers for seeding remote_mcp_servers rows in tests across packages that depend on a remote MCP server FK.
|
Package remotemcptest provides helpers for seeding remote_mcp_servers rows in tests across packages that depend on a remote MCP server FK. |
|
internal/remotesessions
Package remotesessions implements the management API services that surface remote_session_issuer / remote_session_client / remote_session resources — Gram-as-OAuth-Client configuration and the upstream sessions Gram is holding on a principal's behalf.
|
Package remotesessions implements the management API services that surface remote_session_issuer / remote_session_client / remote_session resources — Gram-as-OAuth-Client configuration and the upstream sessions Gram is holding on a principal's behalf. |
|
internal/remotesessions/interceptors
Package interceptors adapts the outgoing upstream authorize request to a provider's non-standard requirements before the user is redirected to it.
|
Package interceptors adapts the outgoing upstream authorize request to a provider's non-standard requirements before the user is redirected to it. |
|
internal/risk/categories
Package categories is the single source of truth for the (source, rule_id) → risk category mapping shown across the dashboard.
|
Package categories is the single source of truth for the (source, rule_id) → risk category mapping shown across the dashboard. |
|
internal/risk/celenv
Package celenv defines the single CEL environment for risk rule expressions.
|
Package celenv defines the single CEL environment for risk rule expressions. |
|
internal/risk/presetlib
Package presetlib classifies risk findings from ANY detection source against a git-versioned catalog of known-benign values (test credit cards, example API keys/tokens, module hashes, placeholder emails).
|
Package presetlib classifies risk findings from ANY detection source against a git-versioned catalog of known-benign values (test credit cards, example API keys/tokens, module hashes, placeholder emails). |
|
internal/risk/presidiofp
Package presidiofp classifies Presidio PII findings as false positives.
|
Package presidiofp classifies Presidio PII findings as false positives. |
|
internal/scanners/accountidentity
Package accountidentity is the single home for the account-identity scanner.
|
Package accountidentity is the single home for the account-identity scanner. |
|
internal/scanners/clidestructive
Package clidestructive is the single home for the destructive-CLI-command scanner.
|
Package clidestructive is the single home for the destructive-CLI-command scanner. |
|
internal/scanners/destructivetool
Package destructivetool is the single home for the destructive-tool-annotation scanner.
|
Package destructivetool is the single home for the destructive-tool-annotation scanner. |
|
internal/scanners/gitleaks
Package gitleaks is the single home for gitleaks-based secret scanning.
|
Package gitleaks is the single home for gitleaks-based secret scanning. |
|
internal/scanners/promptinjection/openrouter
Package openrouter holds the OpenRouter-backed prompt-injection judge.
|
Package openrouter holds the OpenRouter-backed prompt-injection judge. |
|
internal/scanners/promptpolicy/openrouter
Package openrouter holds the OpenRouter-backed prompt policy evaluator.
|
Package openrouter holds the OpenRouter-backed prompt policy evaluator. |
|
internal/scanners/shadowmcpscan
Package shadowmcpscan is the single home for the shadow-MCP scanner.
|
Package shadowmcpscan is the single home for the shadow-MCP scanner. |
|
internal/telemetry/telemetryerrs
Package telemetryerrs holds telemetry errors that non-telemetry packages need to recognize (e.g.
|
Package telemetryerrs holds telemetry errors that non-telemetry packages need to recognize (e.g. |
|
internal/testmcp
Package testmcp provides an in-process mock MCP server backed by the official MCP Go SDK.
|
Package testmcp provides an in-process mock MCP server backed by the official MCP Go SDK. |
|
internal/thirdparty/loops
Package loops is a thin transport wrapper around the Loops transactional email API (https://loops.so).
|
Package loops is a thin transport wrapper around the Loops transactional email API (https://loops.so). |
|
internal/thirdparty/slack/api
Package api provides the shared low-level Slack Web API client used across Gram.
|
Package api provides the shared low-level Slack Web API client used across Gram. |
|
internal/toolconfig
Package toolconfig provides configuration types for tool execution.
|
Package toolconfig provides configuration types for tool execution. |
|
internal/toolref
Package toolref parses and attributes the namespaced tool-call names that agent hosts emit.
|
Package toolref parses and attributes the namespaced tool-call names that agent hosts emit. |
|
internal/urls
Package urls holds validation helpers for URLs that arrive from outside Gram — request payloads, upstream metadata documents, and other untrusted sources — and that Gram stores, dials, or renders as a link.
|
Package urls holds validation helpers for URLs that arrive from outside Gram — request payloads, upstream metadata documents, and other untrusted sources — and that Gram stores, dials, or renders as a link. |
|
internal/usersessions
Package usersessions implements the management API services that surface user_session_issuer / user_session_client / user_session_consent / user_session resources.
|
Package usersessions implements the management API services that surface user_session_issuer / user_session_client / user_session_consent / user_session resources. |
|
internal/uuidv7
Package uuidv7 holds helpers for working with time-ordered UUIDv7 values, chiefly deriving id bounds from timestamps so a (project_id, id) index can double as a time-range filter without a separate created_at index.
|
Package uuidv7 holds helpers for working with time-ordered UUIDv7 values, chiefly deriving id bounds from timestamps so a (project_id, id) index can double as a time-range filter without a separate created_at index. |
|
internal/xmcp
Package xmcp implements the experimental MCP runtime endpoint at /x/mcp/{slug}.
|
Package xmcp implements the experimental MCP runtime endpoint at /x/mcp/{slug}. |
|
cmd/cli/gram
module
|
|
|
tunnel
|
|
|
agent
Package agent reverse-proxies a pinned local MCP server over one outbound yamux/WebSocket tunnel.
|
Package agent reverse-proxies a pinned local MCP server over one outbound yamux/WebSocket tunnel. |
|
cmd/tunnel-agent
command
Command tunnel-agent runs the customer-side outbound tunnel agent.
|
Command tunnel-agent runs the customer-side outbound tunnel agent. |
|
cmd/tunnel-gateway
command
Command tunnel-gateway serves public agent connects and internal tunnel forwards.
|
Command tunnel-gateway serves public agent connects and internal tunnel forwards. |
|
route
Package route stores live tunnel gateway owners and connection snapshots.
|
Package route stores live tunnel gateway owners and connection snapshots. |
Click to show internal directories.
Click to hide internal directories.