11. Directory Structure & On-Disk Files

omicos stores data in two places: a global directory (bound to the user, shared across workspaces) and a workspace directory (bound to the directory you started it in). Understanding this layout makes troubleshooting, backups, and environment migration much easier.

11.1 The Global Directory ~/.omicos/

Bound to your account / machine, shared by all workspaces. The location can be overridden with OMICOS_LOCAL_HOME.

ls ~/.omicos

Expected output:

a2a.json    auth.json        cloud-models        memory
a2a_keys.json    cloud-agents        cloud_login.json    oauth
active_domain    cloud-skills        env            plan_token.jwt
Entry Purpose
cloud_login.json Global copy / fallback of login credentials (omicos login writes here by default; the daemon prefers the workspace-local version), permissions 0600
auth.json Fallback file storage for API keys (see Chapter 12)
plan_token.jwt Subscription token, permissions 0600, auto-renewed in the background
a2a.json / a2a_keys.json Agent2Agent endpoint config and issued API keys (hashes only). Available in releases after 0.3.29; absent if you've never used A2A
active_domain The current content domain, which determines which agent / skill catalog gets pulled
.kernel_choice The persisted kernel interpreter choice (hidden file, only visible with ls -a)
env/ The shared Python environment managed by omicos (contains a .venv)
memory/ Long-term memory across conversations (.md files) — the memory files themselves live here, this isn't a cache
cloud-agents/ cloud-skills/ cloud-models/ Agent / skill / model catalog caches synced from the cloud
oauth/ Third-party OAuth credentials (codex.json / gemini_cli.json)

11.2 The Workspace Directory <workspace>/.omicos/

Bound to the directory you started omicos in, holding that workspace's sessions, trajectories, and locks. serve uses .omicos by default; when cli starts its own daemon it defaults to .omicos/cli (controlled by --data-dir).

ls ~/my-analysis/.omicos

Expected output (a workspace that's logged in and has been used for a while):

account.json        conversations        serve.pid        trajectories
cloud_login.json    conversations.json    settings        usage
conversation_sync.state.json                timeline    tool_outputs
workspace_id
Entry Purpose
workspace_id Persistent 32-char hex id, determines the cloud process_id
serve.pid Daemon lock, two lines: line 1 is the pid, line 2 is the port
cloud_login.json Workspace-local login credentials (the daemon prefers reading here), permissions 0600
account.json Local login-state record
settings/ This workspace's model / provider configuration
conversations/ Session content, one directory per session (containing meta.json, history.jsonl, outputs/, uploads/)
conversations.json Session index
conversation_sync.state.json Session sync progress record
trajectories/ Audit log for each analysis turn, see below
usage/ Usage records counted per LLM call (<session>.jsonl)
tool_outputs/ Overflow storage for tool results (can have many entries)
timeline/ Timeline (may be empty)
updater/ Staged new binary for auto-update (only exists once one has been downloaded)
agents/ skills/ Local overrides for lab+ subscriptions, only exist once you've created one yourself

trajectories/ is isolated internally by login account:

ls ~/my-analysis/.omicos/trajectories

Expected output:

3e81b60c-7d24-42af-9a15-c0f5e8d31b77    anonymous
  • <owner_id>/ — one directory per login account id (since 2026-05), so multiple accounts sharing one workspace folder never mix. Inside, each session gets its own append-only <session_id>.jsonl, auto-synced to the cloud.
  • anonymous/ — records produced before login land here. They aren't migrated automatically after logging in: the same directory may have been used by multiple accounts, so ownership can't be determined after the fact.
  • Loose .jsonl files sitting directly under trajectories/, left over from even older versions, have no provable ownership and are excluded from account-scoped reads (they can be claimed with omicos recover-conversations, see Chapter 9).

Many of the directories above only appear once they're used, so a clean workspace won't necessarily have all of them.

11.3 Data Directories for serve and cli

Mode Default data_dir
omicos serve <workspace>/.omicos
omicos cli (when it starts its own daemon) <workspace>/.omicos/cli

The two keep their sessions and trajectories completely isolated and invisible to each other. That's why, in the web process selector, an entry with a (cli) suffix and one without it are two separate namespaces.

Note: when a omicos serve instance is already running in the workspace, omicos cli connects directly to it and uses serve's data directory — both sides see the same history.

11.4 Details on a Few Key Files

File Description
workspace_id 32-char hex, no hyphens (not the standard dashed UUID form). It determines the cloud process_id (local-<workspace_id>), so renaming or relocating the workspace directory doesn't change the process identity. Rotated to a new value when an identity conflict occurs during an account switch.
serve.pid Two lines: pid + port. A clean process exit removes it automatically; a stale lock left by a force-kill is detected and reclaimed on the next start once the holder is found gone.
cloud_login.json The daemon prefers reading the workspace-local copy first, with the global one as a fallback. Deleting it logs that workspace out. Permissions 0600 — never leak it.
.kernel_choice Records your chosen kernel interpreter, takes priority over OMICOS_KERNEL_PYTHON. If you set the environment variable and it doesn't take effect, check this file first (see Chapter 4).

11.5 Overriding Locations with Variables

Variable / Flag What it overrides
OMICOS_LOCAL_HOME The root of the global directory (credentials, env/, cache, etc.)
OMICOS_USER_HOME The "one per user" global root, for multi-workspace launchers; follows the one above when unset
OMICOS_WORKSPACE_ROOT The workspace root (where sessions / trajectories are stored)
--data-dir The workspace data directory (defaults to <workspace>/.omicos)

11.6 Backup & Migration Recommendations

  • What to back up: ~/.omicos/memory/ (long-term memory), and each workspace's conversations/ and trajectories/.
  • What you don't need to back up: cloud-agents/ cloud-skills/ cloud-models/ (re-sync from the cloud), env/ (rebuildable with omicos env setup), updater/, tool_outputs/.
  • What you must never leak: cloud_login.json, auth.json, plan_token.jwt, a2a_keys.json, oauth/.

results matching ""

    No results matching ""