Skip to main content
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

PathPurpose
~/.holo/.envHosted-mode HAI_API_KEY written by holo login.
~/.holo/profile.jsonCached 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/stopLocal stop signal written by double-Esc and holo stop.
~/.holo/skills/Installed HoloDesktop CLI skills.
~/.holo/settings.jsonClient settings such as seeded skills.
~/.holo/agents.mdStanding HoloDesktop CLI instructions.
~/.holo/memories.mdGeneral memories loaded into HoloDesktop CLI sessions.
~/.holo/holo-memories.mdHoloDesktop CLI-specific memories loaded into sessions.
~/.holo/rules.mdRules 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:
  1. hai-agent-runtime on PATH;
  2. managed install under ~/.holo/runtime/;
  3. 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: 
uv 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.

​
Stop Signal

Double-Esc and holo stop write a timestamped stop signal to: 
~/.holo/stop
Active runs only honor stop signals newer than the run start time, so a stale stop file does not cancel the next run. If double-Esc is not working for MCP or ACP, check that the guard is installed and look for guard logs under: 
~/.holo/logs/holo-guard.log

​
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. 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: 
uv run holo install claude-code
Run install commands from the workspace where you expect the host to discover HoloDesktop CLI.