The LatchAI home

All of your instance data lives in the LatchAI home, a directory that is deliberately outside the code repository. The repo contains code; the home contains your work. That separation is what lets you pull a new version of LatchAI without touching a single thing you made.

Where the home lives

The home is resolved in this order: the LATCHAI_HOME environment variable, then the pointer file at ~/.config/latchai/home (written by onboarding), then the ~/LatchAI default. Whichever wins, the engine bootstraps the layout on boot — the operation is idempotent, so an existing home is never overwritten.

To see which one won, ask the engine:

curl -s localhost:7777/api/home
# {"path":"/Users/you/LatchAI"}

The layout

~/LatchAI/
  agents/            named personas as markdown + frontmatter
  workflows/         graph JSON — the canonical workflow format
  dashboards/        dashboard briefs (markdown + frontmatter)
  widgets/           the widget catalog agents draw with
  atlas/             Code Atlas definitions
  workspace/         the vault: files agents read and write
  models/            model weights downloaded to run on this Mac
  runs/              runtime state (never hand-edit)
  history/           coalesced version history
  latchai.config.json   providers + embeddings
  mcp.json           MCP server declarations
  mounts.json        folders added to the workspace

Every one of those is a file you can open, diff, and commit:

Path	What’s in it
agents/assistant.md	The seeded starter agent: YAML frontmatter (name, description, model, memory) over a markdown system prompt.
workflows/welcome.json	The seeded workflow: { id, name, description, nodes: [...], edges: [...] }, positions included so layout survives a round-trip.
dashboards/morning-briefing.md	A dashboard brief — frontmatter declares the slots, the body is the instruction an agent follows to fill them.
widgets/*.md	One file per widget type the dashboard author may draw with.
atlas/*.md	Code Atlas definitions — what to survey and how to present it.
models/<org>/<repo>/	Weights downloaded from the Models page, one folder per model — delete from the UI rather than by hand while a model is loaded.
latchai.config.json	Connected providers, the default model, and the embeddings endpoint. See Models.
mcp.json	{ "servers": { … } } — stdio or HTTP MCP servers.
mounts.json	{ "<name>": "/absolute/path" } — the folders you added to the workspace.
secrets.index.json	Names only, never values. See Secrets.

workspace/ — the vault

workspace/ is the root every agent tool resolves against, alongside any folders you mount. It is also where the durable, human-readable output collects: chat transcripts mirror to workspace/chats/ as markdown with YAML frontmatter, agent memory lives at workspace/memory/<agent>/*.md, and dashboard and atlas exports land in workspace/dashboards/ and workspace/atlas/. Point an Obsidian vault at it and everything is indexed and linkable with no configuration.

The home as the workbench sees it — workspace on top, mounts beside it.

Paths in the file explorer, in editor tabs, and in every agent tool call are relative to this root — notes/today.md, not /Users/you/LatchAI/workspace/notes/today.md. A path whose first segment names a mount routes to that mount instead; everything else stays here, and anything that resolves outside the set is refused.

runs/ — runtime state

runs/ is machine-owned: append-only JSONL run logs (runs/<runId>.jsonl), the shadow git repository used for checkpoints (runs/checkpoints.git, with the workspace as its work tree), canonical chat envelopes at runs/chats/<id>.json, the semantic search index (runs/semantic-index.json), and per-build dashboard and atlas documents. Nothing here is meant to be hand-edited — it is the record, not the source.

Two things worth knowing about it. The chat envelopes in runs/chats/ are the exact message history including tool turns, which is what makes a session resumable after a restart — the markdown in workspace/chats/ is the readable mirror, not the source. And the semantic index is keyed by file mtime, so deleting it costs a re-index, not data.

history/ — version history

Saving an agent, skill, workflow, dashboard, widget, or atlas definition records a version under history/<kind>/<name>/. Only the live file is ever read by prompts and the executor; history is a directory nothing else looks at, which is why it can be aggressive about keeping copies without affecting behaviour. See Version history for the coalescing and retention rules.

First boot and seeding

A fresh home is seeded once with a starter assistant agent and a welcome workflow, so there is something to run immediately. The widget catalog is treated as a capability rather than user content: it is re-seeded whenever entries are missing, including in homes created before dashboards existed, and never overwrites an entry you have edited. The same is true of the dashboards/ seed — the Morning Briefing brief is written only when the directory is empty.

Moving the home

Relocating the home moves the content, rewrites the pointer file, and exits the engine — a clean restart is the only safe way to swap out the root every service holds a path into. The desktop shell respawns the engine automatically; a terminal daemon has to be restarted by hand.

Onboarding’s “Choose a different folder…” is the front door. Afterwards, the move is an API call:

curl -XPOST localhost:7777/api/home \
  -H 'content-type: application/json' \
  -d '{"path":"/Volumes/work/LatchAI"}'
# {"ok":true,"path":"/Volumes/work/LatchAI","restarting":true}

Three rules the move follows:

• An existing home is adopted, not overwritten. If the target already looks like a LatchAI home, the pointer is repointed at it and nothing is moved — the reinstall case.
• A non-empty target gets a LatchAI/ subfolder. Picking ~/Documents means “put my LatchAI folder in there”, not “turn Documents into a LatchAI home”.
• The new home cannot live inside the old one, and the path must be absolute.

Cross-device moves (an external volume) fall back to copy-then-remove, so they are slower but work.

Troubleshooting

LATCHAI_HOME wins over the pointer file, and it is per-process. If one terminal exports it and another doesn’t, npm run engine and npm run run are operating on two different homes — the workflow you just saved in the UI won’t be the one the CLI executes. When something is mysteriously missing, check curl -s localhost:7777/api/home against echo $LATCHAI_HOME before looking any further.