> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncall.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure OnCall CLI with per‑user and per‑project settings, plus a small set of environment variables.

O# Settings

OnCall uses two primary configuration files:

* **Global user config** — `~/.openbug/config`
  * Stores your API key and (optionally) other global values.
  * Example:

    ```bash theme={null}
    # 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:

    ```yaml theme={null}
    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:

```bash theme={null}
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:

  ```yaml theme={null}
  logs_available: true
  code_available: true
  ```
* Production:

  ```yaml theme={null}
  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.