11. Directory Structure & On-Disk Files

omicos stores data in two places: global (bound to the user, shared across workspaces) and workspace (bound to your current directory). Understanding this layout helps you troubleshoot problems, back up data, and migrate environments.

11.1 The Global Directory `~/.omicos/`

Bound to your account/machine and shared by all workspaces. You can override its location with OMICOS_LOCAL_HOME.

~/.omicos/
├── 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               # API key fallback storage (see the Provider chapter)
├── plan_token.jwt          # subscription-tier JWT, permissions 0600, auto-renewed in the background
├── env/                    # the shared Python kernel environment managed by omicos (.venv)
├── memory/                 # long-term memory across conversations (.md files)
├── cloud-agents/           # agent cache synced from omicos-admin
├── cloud-skills/           # skill cache
├── cloud-models/           # model catalog cache (models.json)
├── cloud-memory/           # memory sync cache
├── oauth/                  # third-party OAuth credentials (codex.json / gemini_cli.json)
└── usage/                  # usage-audit fallback when there is no workspace

11.2 The Workspace Directory `<workspace>/.omicos/`

Bound to the directory where you started omicos, this holds that workspace's sessions, trajectories, and locks. serve defaults to .omicos, and cli defaults to .omicos/cli (controlled by --data-dir).

Below is the .omicos/ contents of a real, logged-in workspace (serve defaults to .omicos, cli defaults to .omicos/cli, controlled by --data-dir):

<workspace>/.omicos/
├── workspace_id            # persistent 32-char hex id that determines the cloud process_id (stable across directory moves)
├── workspace_id.<user>.bak # backup left behind when switching accounts / rotating workspace_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)
├── cloud_login.json.*.bak  # old backups left behind on credential realign / account switch
├── account.json            # local session record (authenticated / token / plan / email)
├── settings/               # llm-config.json, llm-providers-state.json
├── conversations/          # conversation content (each conversation has history.jsonl, meta.json, outputs/, uploads/)
├── conversations.json      # conversation index
├── conversation_sync.state.json   # conversation sync high-water mark (used by the cloud stale filter)
├── trajectories/           # audit logs for each analysis turn
│   ├── <owner_id>/         # isolated by login account (owner UUID) (since 2026-05), so multiple accounts don't mix
│   │   └── turn_<hex>.jsonl # append-only JSONL, auto-pushed to the cloud
│   ├── anonymous/          # sessions written before login land here
│   └── .sync_state.json    # trajectory upload sync state (recorded per device_id)
├── usage/                  # usage audit counted per LLM call (<session>.jsonl)
├── tool_outputs/           # tool-result overflow storage (can reach hundreds of entries)
├── timeline/               # timeline (may be empty)
├── sidecar-restart.log     # sidecar restart log
├── agents/                 # local agent overrides for lab+ subscriptions (exists only after you create one)
└── skills/                 # local skill overrides for lab+ subscriptions (exists only after you create one)

Note: directories like agents/, skills/, and updater/ appear only when they're used, so a clean workspace may not have them.

11.3 Data-Directory Isolation Between serve and cli

Mode	Default data_dir
`omicos serve`	`<workspace>/.omicos`
`omicos cli`	`<workspace>/.omicos/cli`

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

11.4 What a Few Key Files Do

File	Purpose
`workspace_id`	A persistent 32-char hex id (no hyphens, not a dashed standard UUID). It determines the cloud `process_id` (`local-<workspace_id>`), so even if you rename or relocate the workspace directory, the process identity stays stable.
`serve.pid`	The workspace lock (two lines: pid + port), guarded via RAII — a clean process exit clears it automatically; a stale lock left behind by a `SIGKILL` is automatically reclaimed on the next start.
`cloud_login.json`	Workspace-local login credentials. The daemon prefers reading here (with the global `~/.omicos/cloud_login.json` as a fallback). Deleting it logs you out of that workspace. Permissions 0600 — never leak it.
`trajectories/<owner_id>/`	Since 2026-05, trajectories are split into per-account directories by owner UUID, ensuring that records from multiple accounts in the same workspace folder don't mix; file names look like `turn_<hex>.jsonl`.

11.5 Overriding Locations with Variables

Variable	What it overrides
`OMICOS_LOCAL_HOME`	The root location of the global directory (credentials, workspace_id, etc.).
`OMICOS_WORKSPACE_ROOT`	The workspace root (where sessions/trajectories are stored).
`--data-dir`	The workspace data directory (defaults to `workspace_root/.omicos`).

11.6 Backup & Migration Recommendations

What to back up: ~/.omicos/memory/ (long-term memory), plus each workspace's conversations/ and trajectories/.
What you don't need to back up: the cloud-*/ caches (they re-sync from the cloud), env/ (you can rebuild it with omicos env setup), updater/, and tool_outputs/.
What you must never leak: cloud_login.json, auth.json, plan_token.jwt, and oauth/.

results matching ""

No results matching ""