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

# Configuration File

> Ultra's YAML configuration format and options

Ultra uses a YAML configuration file to define upstream servers, observability settings, and Hub connection details.

## Config Search Order

Ultra searches for configuration files in this order (first match wins):

1. `ultra.yaml` or `ultra.yml` (current directory)
2. `.ultra.yaml` or `.ultra.yml` (current directory)
3. `$XDG_CONFIG_HOME/ultra/config.yaml` (default: `~/.config/ultra/config.yaml`)
4. `$XDG_CONFIG_HOME/ultra/config.yml`
5. `~/.ultra.yaml` or `~/.ultra.yml`

If no config file is found, Ultra uses sensible defaults.

## Show Config Path

```bash theme={null}
ultra config path
```

## Default Config Path

```
~/.config/ultra/config.yaml
```

## Full Example

```yaml theme={null}
version: "1"

server:
  name: ultra
  log_level: info    # debug, info, warn, error

upstream:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
    description: "Local filesystem access"

  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "ghp_xxxxxxxxxxxx"
    enabled: true

  notion:
    url: "https://mcp.notion.so"
    headers:
      Authorization: "Bearer secret_xxxxxxxxxxxx"
    enabled: true

observability:
  enabled: false     # Set to true for OTLP export
  endpoint: ""       # e.g., "localhost:4317"
  service_name: ultra

hub:
  enabled: false
  url: "https://hub.ultra.security"
  sync_interval: "60s"
  offline_mode: false
```

## Configuration Reference

### `server`

| Field       | Type   | Default   | Description                                     |
| ----------- | ------ | --------- | ----------------------------------------------- |
| `name`      | string | `"ultra"` | Server name advertised to MCP clients           |
| `log_level` | string | `"info"`  | Logging level: `debug`, `info`, `warn`, `error` |

### `upstream`

A map of named upstream MCP servers. Each server uses either **stdio** transport (command) or **HTTP** transport (url).

| Field         | Type      | Required  | Description                                    |
| ------------- | --------- | --------- | ---------------------------------------------- |
| `command`     | string    | For stdio | Command to execute                             |
| `args`        | string\[] | No        | Command arguments                              |
| `env`         | map       | No        | Environment variables                          |
| `url`         | string    | For HTTP  | HTTP URL for remote servers                    |
| `headers`     | map       | No        | HTTP headers (e.g., auth tokens)               |
| `enabled`     | bool      | No        | Whether this server is active (default: false) |
| `description` | string    | No        | Human-readable description                     |

<Warning>
  Each upstream must specify either `command` or `url`, not both.
</Warning>

### `observability`

| Field          | Type   | Default   | Description                            |
| -------------- | ------ | --------- | -------------------------------------- |
| `enabled`      | bool   | `false`   | Enable OTLP telemetry export           |
| `endpoint`     | string | `""`      | OTLP endpoint (e.g., `localhost:4317`) |
| `service_name` | string | `"ultra"` | Service name for telemetry             |

### `hub`

| Field           | Type   | Default                        | Description                                |
| --------------- | ------ | ------------------------------ | ------------------------------------------ |
| `enabled`       | bool   | `false`                        | Enable Hub sync                            |
| `url`           | string | `"https://hub.ultra.security"` | Hub API URL                                |
| `gateway_id`    | string |                                | Assigned by Hub during linking             |
| `sync_interval` | string | `"60s"`                        | Sync frequency (e.g., `"60s"`, `"5m"`)     |
| `offline_mode`  | bool   | `false`                        | Allow operation without Hub connectivity   |
| `deploy_key`    | string |                                | Static API key for CI/headless deployments |

<Note>
  Hub authentication tokens (`access_token`, `refresh_token`, `token_expiry`) are managed automatically by `ultra login` and should not be edited manually.
</Note>

### Policy enforcement

Policy enforcement is not configured in this file. [Guardrails](/hub/guardrails) and [governance rules](/hub/governance) are configured in Ultra Hub and synced automatically to every connected gateway, so enforcement stays consistent across your fleet without editing local config.

## File Permissions

The config file is saved with `0600` permissions (owner read/write only) because it may contain authentication tokens and API keys.

## Programmatic Config Management

Use `ultra config` subcommands to modify configuration:

```bash theme={null}
# Set an auth token for a server
ultra config set-token github-mcp-server YOUR_TOKEN

# Set a custom header
ultra config set-header my-server X-API-Key YOUR_KEY

# Show config file path
ultra config path
```