Skip to main content
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:
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:
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:
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. 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. 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.
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:
If your server needs a model ID, set it too:
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.