> ## 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.

# Hosted or local models

> Choose how HoloDesktop CLI calls a model backend for desktop tasks.

Before HoloDesktop CLI can run a task, it needs a model. You have two choices: H Company's hosted Models API, or a model you run yourself and point the CLI at over an OpenAI-compatible server.

Hosted mode is the default. Local mode kicks in the moment you provide a local base URL.

## Hosted mode

Sign in once:

```bash theme={null}
holo login
```

This opens the H Company Portal in your browser. After sign-in, the CLI writes a hosted API key to `~/.holo/.env`. Check that the key is available:

```bash theme={null}
holo whoami
```

You can also provide `HAI_API_KEY` through the process environment. When the key comes from the environment, `holo whoami` may not have a cached Portal identity to print.

To pick a hosted model explicitly, pass its API model ID:

```bash theme={null}
holo run --model holo3-1-35b-a3b "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
```

For the larger Holo3 hosted model, use `--model holo3-122b-a10b`.

MCP and ACP hosts cannot complete browser login during startup, because they launch the CLI non-interactively. If you plan to use hosted mode from a host, run `holo login` in a terminal first, then restart the host so it can see the saved key.

## Local mode

Local mode runs one of H Company's open-weight models on your own machine, for fully private, on-device inference. You bring up an OpenAI-compatible server, then point the CLI at it.

To set up the server itself, follow [Run a local model server](/holo-desktop-cli/how-to/run-a-local-model-server). It covers llama.cpp on macOS and vLLM on DGX Spark, including tuned launch flags. Open-weight weights live in the [H Company Hugging Face org](https://huggingface.co/Hcompany).

With a server running, point the CLI at it with two flags:

* `--base-url`: the address of your local server, such as `http://localhost:8080/v1` (llama.cpp) or `http://localhost:8000/v1` (vLLM).
* `--model`: the model ID. Any string works for llama.cpp; for vLLM it must match the `--served-model-name` you set when launching the server.

```bash theme={null}
holo run "Open TextEdit and write hello" \
  --base-url http://localhost:8080/v1 \
  --model holo3-1-35b
```

Local mode is selected the moment you provide `--base-url` or `HAI_AGENT_RUNTIME_BASE_URL`, and does not require `holo login` when the endpoint is reachable.

### Local mode from hosts

MCP and ACP hosts start the CLI over stdio, so they read model settings from the environment that launched the host. Set the local server URL before the host starts the CLI:

```bash theme={null}
export HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
```

If your server needs a model ID, set it too:

```bash theme={null}
export HAI_AGENT_RUNTIME_MODEL=Hcompany/Holo-3.1-35B-A3B
```

When `HAI_AGENT_RUNTIME_BASE_URL` is set, MCP and ACP startup does not require `HAI_API_KEY`. Shell exports usually do not reach GUI apps launched from the Dock or Finder, so if local mode works in your terminal but fails in a host, put `HAI_AGENT_RUNTIME_BASE_URL` and `HAI_AGENT_RUNTIME_MODEL` in the host's own MCP or ACP environment config.

## Which should I use?

Use hosted mode for the fastest setup. Use local mode for private inference, local model serving, or direct control over the model runtime.

## What's next

After hosted login succeeds or your local server is running, run your first task with the [Quickstart](/holo-desktop-cli/getting-started/quickstart).