Skip to content

System Files Reference

This subtree is the centralized reference for filesystem paths that Houmao creates, selects, or relies on during normal runtime, registry, and server lifecycles.

Use it when you need to answer questions like:

  • which directories Houmao will create,
  • which files are durable contracts versus current implementation details,
  • which roots can be redirected,
  • which paths should be writable before launch,
  • which directories are safe to treat as scratch.

Mailbox is intentionally out of scope here because it is a separate filesystem subsystem with its own reference tree. Use Mailbox Reference for mailbox-owned roots and contracts.

Quick Map

Representative Houmao-owned roots for maintained local-state command flows:

<active-overlay>/
  runtime/
  memory/
  mailbox/                  # documented separately

~/.houmao/
  registry/

Representative runtime-owned layout:

<active-overlay>/runtime/
  homes/<home-id>/
  manifests/<home-id>.yaml
  sessions/<backend>/<session-id>/
  houmao_servers/<host>-<port>/

Representative registry-owned layout:

~/.houmao/registry/
  live_agents/<agent-id>/record.json

Representative launcher-owned layout:

<runtime-root>/cao_servers/<host>-<port>/
  launcher/
  home/

Read By Goal

For maintained local-state command surfaces, runtime/, managed-agent memory state under memory/, and mailbox/ now default from one active project overlay. The shared ~/.houmao/ anchor remains the default home for registry state and the explicit legacy-root target for operators who intentionally override runtime or mailbox placement.

  • Roots And Ownership: Default roots, override precedence, ownership categories, and the mailbox boundary.
  • Agents And Runtime: Generated homes, generated manifests, runtime session roots, nested gateway files, and per-agent memory directories.
  • Legacy CAO Server: Historical reference for the retired standalone CAO launcher layout.
  • Houmao Server: Server-owned listener roots, registration bridges, and memory-primary live tracking.
  • Shared Registry: Registry root placement, live_agents/<agent-id>/record.json, and the registry’s pointer-oriented scope.
  • Operator Preparation: Pre-creation, permissions, redirection surfaces, ignore rules, and cleanup expectations.

Source References