Directories

Everything keelson manages lives in one directory, the home, resolved deterministically at every entry point. Secrets are the single exception: they live in your OS keychain, never in the home. Below is the exact layout, and the variables that relocate each piece.

How the home resolves

The home is the first of these that applies, checked in order:

Precedence	Source	When it wins
1	`KEELSON_HOME`	Set and non-empty. The explicit override.
2	An existing `.keelson/` walking up from the working directory	The monorepo dev layout, where the home is `<repo>/.keelson`.
3	The per-user default	Everything else. `~/.keelson` on macOS and Linux; on Windows see below.

The walk-up branch is what lets keelson data live beside an embedding project’s source during development; an installed harness almost always lands on the per-user default.

On Windows the per-user default is %LOCALAPPDATA%\keelson, not %USERPROFILE%\.keelson. The home holds node_modules, a live SQLite database, and a pid file — none of which should follow a user between machines, and %USERPROFILE% roams in AD environments. An existing %USERPROFILE%\.keelson still wins, so upgrading an install that predates the move never relocates its data; only a fresh install lands in %LOCALAPPDATA%. With no %LOCALAPPDATA% set, the profile path is the fallback.

What lives in the home

Path	What
`keelson.db`	The SQLite store: conversations, workflow runs and node outputs, projects and notebooks, memory rows.
`config.json`	The operator’s settings: provider enablement and defaults, cross-rib grants, the MCP gateway block, registered gateways, and the Claude and Codex provider blocks. Optional; a missing file falls back to defaults.
`server.json`	The running server’s record: URL, pid, version, schema version, start timestamp, shutdown token, and (when MCP token-gating is enabled) an MCP token. Written on start, cleaned on stop.
`workflows/`	Your global workflow YAML files.
`commands/`	Named markdown prompt files a workflow `command` node runs.
`artifacts/`	Published canvas artifacts, one `<slug>.html` page (openable in any browser) plus a `<slug>.json` sidecar; re-registered at boot.
`node_modules/@keelson/`	Installed rib packages, discovered at boot.
`rib-<id>/`	Private data directory for a rib that calls `getDataDir()`. Created on first write; named to mirror the `@keelson/rib-<id>` package.
`logs/server.log`	The background server’s log, named in the error hints when something is wrong.

Relocating pieces

Each path has an override, applied over the resolved home:

Variable	Relocates
`KEELSON_HOME`	The whole home.
`KEELSON_DB`	The database file (for `keelson start --db`, too).
`KEELSON_WORKFLOWS_DIR`	The global workflows directory.
`KEELSON_CONFIG`	The config file.

See Configuration for the full KEELSON_* table.

Project-local state

A registered project carries its own .keelson/ under its root path. Today that holds workflows/: a project workflow shadows a same-named global one within that project. Conversations and runs attach to the project, and memory recall is scoped by it. A git-worktree isolated run (workflow run --worktree) checks out under <project>/.worktrees/, and keelson worktree prune sweeps the leftovers there, not in the home.

Secrets are not here

No secret is stored in the home. Provider keys and rib credentials live in the OS keychain under the keelson service; the database and the API only ever report that a credential exists, never its value. The split is the trust model: data you may want to inspect sits in files you can open, and secrets sit behind the operating system’s own lock.

Operating the server: server.json, the shutdown token, and the service lifecycle.
Configuration: the KEELSON_* variables and the config file.
Memory and state: what the database holds and how secrets stay out of it.