Skip to main content
Reach for the Python client when you want desktop sessions inside your own code, a script, demo harness, test runner, or local tool, instead of shelling out to holo run. The Python client starts or attaches to the same local hai-agent-runtime process used by the CLI, MCP, and ACP surfaces.

Basic script

After installing HoloDesktop CLI, import the agent client from holo_desktop:
Run it with:
From a source checkout, run it through uv instead: uv run python your_script.py.

Use hosted or local mode

Hosted mode uses the same login state as the CLI. Sign in once:
Local mode passes model settings at runtime spawn:
The model and base URL are process-level settings. Start a separate runtime process when you need to switch model backend.

Keep logs for a run

To choose where runtime event logs are written:
The CLI equivalent is:

Send another message

The client exposes pause, resume, cancel, and mid-run messages:
Use these methods for interactive tools. For one-shot scripts, create a session, stream to end-of-turn, and close the daemon.

Handle cleanup

Always close the daemon:
If your script spawned the runtime, closing the daemon stops it. If it attached to an already-running runtime on the same port, closing the daemon only releases the client-side handle. If your program is interrupted while a session is active, cancel the session or close the daemon before exiting, or the runtime may keep working until its timeout or safety budget.

What to avoid

  • Do not pass secrets or hidden context only in your app state. HoloDesktop CLI sees the task string and the configured ~/.holo context, not your surrounding Python variables.
  • Do not switch model or base_url per session. Those are runtime process settings.
  • Do not leave a session running after your program exits. Cancel or close when interrupted.

What’s next

Use Debug a failed run to inspect runtime logs, or see the expense-report example for a larger tested harness.