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

# Environment variables

> Environment variables used by HoloDesktop CLI and hai-agent-runtime.

Most users only need `HAI_API_KEY` for hosted mode or `HAI_AGENT_RUNTIME_BASE_URL` for local mode. The rest are useful for host integrations, debugging, or advanced runtime control.

## Model and credentials

| Variable                     | Purpose                                                                     |
| ---------------------------- | --------------------------------------------------------------------------- |
| `HAI_API_KEY`                | Hosted-mode API key for H Company's Models API.                             |
| `HAI_AGENT_RUNTIME_BASE_URL` | OpenAI-compatible local model endpoint, such as `http://localhost:8000/v1`. |
| `HAI_AGENT_RUNTIME_MODEL`    | Model ID passed to the runtime, such as `Hcompany/Holo-3.1-35B-A3B`.        |

`holo login` stores `HAI_API_KEY` in:

```text theme={null}
~/.holo/.env
```

The client loads environment in this order:

1. process environment;
2. `~/.holo/.env`;
3. `.env` in the current working directory.

Process environment wins over files.

## Runtime

| Variable                      | Purpose                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `HAI_AGENT_RUNTIME_PORT`      | Agent API port. Defaults to `18795`.                                                              |
| `HAI_AGENT_RUNTIME_API_TOKEN` | Bearer token for the loopback agent API. If unset, the client generates one for spawned runtimes. |
| `HAI_AGENT_RUNTIME_RUNS_DIR`  | Runtime event-log directory. If unset, the runtime default is `~/.holo/runs`.                     |
| `HAI_AGENT_RUNTIME_FAKE`      | Test mode flag. Values `1`, `true`, or `yes` enable fake-agent mode.                              |
| `HOLO_AUTH_TOKEN`             | Bearer token clients present to the `holo serve` A2A server.                                      |

For host integrations, set model variables in the host's configuration if the host is launched from a GUI and does not inherit your shell exports.

Example MCP environment:

```json theme={null}
{
  "mcpServers": {
    "holo": {
      "command": "holo",
      "args": ["mcp"],
      "env": {
        "HAI_AGENT_RUNTIME_BASE_URL": "http://localhost:8000/v1",
        "HAI_AGENT_RUNTIME_MODEL": "Hcompany/Holo-3.1-35B-A3B"
      }
    }
  }
}
```

## Runtime download overrides

These are for tests, operations, or trusted development builds:

| Variable                            | Purpose                                                       |
| ----------------------------------- | ------------------------------------------------------------- |
| `HAI_AGENT_RUNTIME_DOWNLOAD_URL`    | Override the managed runtime download URL.                    |
| `HAI_AGENT_RUNTIME_DOWNLOAD_SHA256` | Required sha256 when `HAI_AGENT_RUNTIME_DOWNLOAD_URL` is set. |

HoloDesktop CLI refuses an unverified download URL. Set both values or neither.

## Development and tests

Some repository tests use opt-in variables such as `HOLO_RUN_INTEGRATION`, `HOLO_IT_BASE_URL`, and `HOLO_IT_MODEL`. These are test harness variables, not end-user configuration.

For normal local model use, prefer:

```bash theme={null}
holo run \
  --base-url http://localhost:8000/v1 \
  --model Hcompany/Holo-3.1-35B-A3B \
  "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
```

For host-launched stdio servers, use:

```bash theme={null}
export HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
export HAI_AGENT_RUNTIME_MODEL=Hcompany/Holo-3.1-35B-A3B
```