Skip to main content
OnCall uses two primary configuration files:
  • Global user config — ~/.openbug/config
    • Stores your API key and (optionally) other global values.
    • Example: 
      # OpenBug Configuration File
#
# Place your OpenBug API key here.
# You can get a key from the OpenBug dashboard.
#
API_KEY=your-api-key-here
  • Per-service config — oncall.yaml (in each project root)
    • Describes a single service in your app and how OnCall can interact with it.
    • Example: 
      id: "openbug-service"           
description: "Node.js API backend"
name: "API Backend"
window_id: 1765367571382        # Unique service instance ID
logs_available: true            # Allow AI to read logs
code_available: true            # Allow AI to read code

​
~/.openbug/config (user settings)

Used to configure values that apply to all projects on a machine:
  • API_KEY — required; used to authenticate to the OpenBug debugging service.
    • Set with debug login <api-key>.
    • Rotated by updating the file via debug login and deleting old keys in the dashboard.
You typically do not edit this file by hand; use CLI commands instead.

​
openbug.yaml (project/service settings)

Each project directory that uses OpenBug CLI should have exactly one openbug.yaml. It is created with: 
debug init -m "Describe this service" -id "<project-id>"
Key fields:
  • id (string): Project ID
    • All services with the same id are treated as part of a single logical app/cluster.
  • description (string): Short description of the service
    • Used to give the AI more context about what this service does.
  • name (string): Optional display name for the service
  • window_id (number): Unique identifier for this service instance
    • Auto-generated; do not edit manually.
  • logs_available (boolean):
    • If true, allows log tools (read_logs, tail_logs, grep_logs, get_recent_errors) for this service.
    • If false, these tools are blocked; the AI only sees logs you paste or embed.
  • code_available (boolean):
    • If true, allows code tools (read_file, grep_search) for this service.
    • If false, the AI cannot read or search code for this service.
Recommended patterns:
  • Development: 
    logs_available: true
code_available: true
  • Production: 
    logs_available: true
code_available: false

​
Environment variables

OpenBug CLI also respects a small number of environment variables for advanced configuration:
  • Cluster server configuration:
    • OPENBUG_CLUSTER_URL — WebSocket URL for the local cluster server.
      • Default: ws://127.0.0.1:4466
    • OPENBUG_WS_PORT — Port used by the cluster server when running debug.
    • OPENBUG_WS_HOST — Host used by the cluster server when running debug.
These are typically only changed if you’re routing traffic through custom infrastructure or running the cluster server on a non-default host/port.

​
Settings precedence

When the CLI runs a command (for example, debug npm run dev), it loads configuration in this order:
  1. Environment variables (if set).
  2. ~/.openbug/config for user-level values like API_KEY.
  3. openbug.yaml in the current working directory for service-level behaviour.
openbug.yaml always controls per-service access to logs and code, regardless of any environment variables.

​
Best practices

  • One openbug.yaml per service
    • Check this file into source control so your team shares the same description, project ID, and access flags.
  • Separate keys per environment or team
    • Use distinct API keys in ~/.openbug/config on different machines/environments so dashboard usage is naturally segmented.
  • Align flags with risk level
    • Enable full access (logs + code) in development to get the richest assistance.
    • Restrict code access in production and other sensitive environments.
  • Keep settings simple
    • Prefer using debug init, debug login, and editing openbug.yaml over introducing many custom environment overrides—this keeps your setup easier to understand for the whole team.