Skip to main content
OnCall uses two primary configuration files:
  • Global user config – ~/.oncall/config
    • Stores your API key and (optionally) other global values.
    • Example: 
      # OnCall Configuration File
#
# Place your OnCall API key here.
# You can get a key from the OnCall 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: "my-app"                    # Project ID for clustering
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

​
~/.oncall/config (user settings)

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

​
oncall.yaml (project/service settings)

Each project directory that uses OnCall CLI should have exactly one oncall.yaml. It is created with: 
oncall 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 – gives 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

OnCall CLI also respects a small number of environment variables for advanced configuration:
  • Cluster server configuration:
    • ONCALL_CLUSTER_URL — WebSocket URL for the local cluster server. Default: ws://127.0.0.1:4466
    • ONCALL_WS_PORT — Port used by the cluster server when running oncall cluster.
    • ONCALL_WS_HOST — Host used by the cluster server when running oncall cluster.
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, oncall npm run dev), it loads configuration in this order:
  1. Environment variables (if set).
  2. ~/.oncall/config for user‑level values like API_KEY.
  3. oncall.yaml in the current working directory for service‑level behavior.
oncall.yaml always controls per‑service access to logs and code, regardless of any environment variables.

​
Best practices

  • One oncall.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 ~/.oncall/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 oncall init, oncall login, and editing oncall.yaml over introducing many custom environment overrides—this keeps your setup easier to understand for the whole team.