Paths and files

HoloDesktop CLI stores local state under:

~/.holo/

Treat this directory as sensitive. It can contain credentials, identity metadata, instructions, skills, screenshots, and run logs.

Core paths

Path	Purpose
`~/.holo/.env`	Hosted-mode `HAI_API_KEY` written by `holo login`.
`~/.holo/profile.json`	Cached identity metadata used by `holo whoami`.
`~/.holo/runtime/`	Managed `hai-agent-runtime` installs.
`~/.holo/logs/`	Runtime startup and stderr logs.
`~/.holo/runs/`	Runtime run artifacts.
`~/.holo/desktop.lock`	Advisory lock so one desktop task runs at a time.
`~/.holo/skills/`	Installed HoloDesktop CLI skills.
`~/.holo/settings.json`	Client settings such as seeded skills.
`~/.holo/agents.md`	Standing HoloDesktop CLI instructions.
`~/.holo/memories.md`	General memories loaded into HoloDesktop CLI sessions.
`~/.holo/holo-memories.md`	HoloDesktop CLI-specific memories loaded into sessions.
`~/.holo/rules.md`	Rules loaded into sessions.

Runtime cache

When hai-agent-runtime is not on PATH, HoloDesktop CLI downloads the pinned runtime version to:

~/.holo/runtime/<version>/

The download is sha256-verified before install. On macOS, the executable lives inside the downloaded app bundle:

~/.holo/runtime/<version>/hai_agent_runtime.app/Contents/MacOS/hai-agent-runtime

HoloDesktop CLI resolves runtime binaries in this order:

hai-agent-runtime on PATH;
managed install under ~/.holo/runtime/;
download-on-first-run.

Logs

Runtime startup logs are written under:

~/.holo/logs/

The file name includes the agent API port:

hai-agent-runtime-18795.log

Use these logs for startup failures, runtime crashes, model backend errors, port conflicts, and permission-looking errors.

Run artifacts

Default run artifacts live under:

~/.holo/runs/

Override the run directory for a single CLI run:

holo run \
  --runs-dir /tmp/holo-runs \
  "Open TextEdit and write the word test"

The most important file is:

events.jsonl

Each line is one runtime event. Observation events can include base64 JPEG screenshots of the visible desktop. Do not publish run directories without reviewing them.

Token files

When HoloDesktop CLI spawns a runtime and no explicit HAI_AGENT_RUNTIME_API_TOKEN is set, it generates a bearer token and publishes it locally so other local clients can attach to the same runtime:

~/.holo/agent-token-<port>

The token file is removed when the owning client closes the spawned runtime.

Skills

Skills are installed under:

~/.holo/skills/<slug>/SKILL.md

Each skill directory name becomes the skill name HoloDesktop CLI sees. Keep directory names lowercase and hyphenated. To author skills, memories, and rules, see Customize with skills, memories, and rules. Bundled skills can be seeded automatically by the client, and examples may install their own skills. The expense-report example installs:

~/.holo/skills/expense-report/SKILL.md

Host config files

Host-specific config locations depend on the host. For Claude Code, project-local MCP config is associated with the workspace where you run:

holo install claude-code

Run install commands from the workspace where you expect the host to discover HoloDesktop CLI.

Get started

Integrations

How-to guides

Reference

Examples

Core paths

Runtime cache

Logs

Run artifacts

Token files

Skills

Host config files

Next steps

Customize the agent

Security and privacy

​Core paths

​Runtime cache

​Logs

​Run artifacts

​Token files

​Skills

​Host config files

​Next steps

Customize the agent

Security and privacy

Core paths

Runtime cache

Logs

Run artifacts

Token files

Skills

Host config files

Next steps