grafana-bridge

Local HTTP proxy that bridges CLI tools, scripts, and AI-powered dashboards to Grafana Cloud instances behind SSO (Okta, Google, Azure AD, etc.).

Install

npx grafana-bridge --grafana-url https://mycompany.grafana.net

Or install globally:

npm install -g grafana-bridge
grafana-bridge -u https://mycompany.grafana.net

Requires Node.js >= 18. Playwright's Chromium is installed automatically via postinstall.

Usage

# Start the proxy
grafana-bridge -u https://mycompany.grafana.net

# With custom port
grafana-bridge -u https://mycompany.grafana.net -p 8080

# With verbose logging
grafana-bridge -u https://mycompany.grafana.net --verbose

# With config file
grafana-bridge -c ./my-config.yaml

Once running, any HTTP client can query Grafana through the local proxy:

# List datasources
curl http://localhost:4000/api/datasources

# Query Loki
curl -X POST http://localhost:4000/api/ds/query \
  -H "Content-Type: application/json" \
  -d '{"queries": [...]}'

# Search dashboards
curl http://localhost:4000/api/search

# Health check
curl http://localhost:4000/health

# Trigger proactive authentication
curl -X POST http://localhost:4000/auth

Configuration

CLI flags

grafana-bridge [options]

  -u, --grafana-url <url>     Grafana instance URL (required)
  -p, --port <number>         Local proxy port (default: 4000)
  -c, --config <path>         Path to config file
  --login-timeout <ms>        SSO login timeout (default: 120000)
  --session-file <path>       Session persistence file path
  --verbose                   Enable debug logging
  -v, --version
  -h, --help

Config file

Place at ~/.config/grafana-bridge/config.yaml or ./grafana-bridge.yaml:

grafanaUrl: 'https://mycompany.grafana.net'
port: 4000
loginTimeoutMs: 120000
sessionFile: '~/.config/grafana-bridge/session.json'
verbose: false

Environment variables

• GRAFANA_BRIDGE_URL — Grafana instance URL
• GRAFANA_BRIDGE_PORT — Local proxy port

Precedence

CLI flags > environment variables > config file > defaults

How it works

1. All requests are forwarded to Grafana with session cookies injected (if a session exists)
2. If Grafana returns 401, a Chromium browser opens for SSO login (lazy authentication)
3. After successful login, grafana_session and grafana_session_expiry cookies are captured
4. Session is cached in memory and persisted to ~/.config/grafana-bridge/session.json
5. Subsequent requests reuse the cached session — the browser only opens when Grafana rejects the session
6. Re-authentication retries up to 3 times before returning 401 to the client
7. Persistent browser context means SSO IdP cookies are remembered — subsequent re-auths only need Grafana consent, not full IdP login
8. POST /auth can be used to proactively trigger authentication before any request

License

MIT