Files and folders

OAR keeps everything it owns in one folder, the state folder: the config file, the database with your conversations, the logs and the uploaded files. This page says where that folder is, what is in it, which parts you can delete, which hold secrets and what the relay removes by itself. Some data is not in the state folder at all: each provider keeps its own session data and logins in its own folders.

The state folder #

npm install -g and oar update replace the package but never touch the state folder. OAR_STATE_ROOT has to be set in every shell where you run oar, or the command looks in the default folder; see Environment variables. oar doctor prints the paths in use: the state folder, the config file, the database and its size. The same paths are listed for each install in Install.

Three environment variables move single parts: COPILOT_WEB_RELAY_CONFIG the config file, COPILOT_WEB_RELAY_DATA_DIR the data folder (database, lock and uploads) and COPILOT_WEB_RELAY_LOG_DIR the log folder. In config.json the key dataDir moves the data folder too; the environment variable wins. A relative dataDir counts from the folder of config.json.

Added in 0.9.14 Uploads follow the data folder too: <dataDir>/uploads. Uploads that earlier versions left in server/uploads, or that a migration copied into the state folder's uploads/, are still read there in place.

Added in 0.9.14 A global install's relay runs on the state folder's data folder however it is started: oar start, the Linux service, both Windows autostart modes and a plain gh copilot with OAR's extension. A dataDir in config.json that an earlier autostart relay used is copied from once and left as it is.

On macOS and Linux the relay makes the data folder readable by you only (mode 700), and the config file and the database files owner-only (mode 600).

Moving an old install #

Before the project was renamed, state lived in a git checkout's server/ folder, and the config file and logs of a checkout's launcher in ~/.config/copilot-remote ($XDG_CONFIG_HOME/copilot-remote when that is set; Windows: %LOCALAPPDATA%\copilot-remote). A global install copies the config file and logs of that folder into the state folder once, with its first oar setup or oar copilot. oar start does not migrate. To import the state of a checkout, which includes its database:

oar setup --migrate-from /home/dev/projects/old-oar

The folder is the checkout itself, not its server/ folder. What happens:

• It copies the database (with its -wal and -shm files), the config file, the Cursor agent stores that were in data/ (only when there was a database), the uploads folder and the logs folder when that is 50 MB or smaller.
• It never changes the source. Delete the old folder yourself when you are satisfied.
• It refuses while a relay still runs from the source, and says so.
• It checks the copy before it counts: the database must pass SQLite's integrity check and hold the same number of conversations and messages. If not, it removes what it copied, Added in 0.9.14 no longer the whole state folder, and leaves a message.
• Added in 0.9.14 It never overwrites. A config.json already in the state folder is kept. The empty database an installer's relay created is moved into backups/ (stop the relay first: oar stop); a database with conversations makes it refuse and say what to do instead. While it copies a database it holds the relay's lock, so no relay starts on it meanwhile.
• It writes a receipt to backups/MIGRATION.md and a marker file .migrated in the state folder.

Added in 0.9.14 Migrated uploads land in data/uploads/, where the relay reads them, and the Cursor agent stores in data/cursor-agents/, which the relay reads by default. Uploads an earlier migration left in the state folder's uploads/ are merged into data/uploads/ at the next relay start; nothing is overwritten or deleted. Symlinked folders in the checkout are copied as real folders.

What is inside #

Paths are relative to the state folder. "Safe to delete" means the relay works afterwards; it says nothing about what you lose.

Outside the state folder, the installer's oar launcher is in ~/.local/bin/oar (only in the cases where it installs into ~/.oar/npm), and the Linux service is ~/.config/systemd/user/oar.service. Removing them is described in Removing OAR. Added in 0.9.15 oar uninstall removes the service and the package and leaves the state folder as it is; oar uninstall --purge deletes it, after you type delete.

A git checkout keeps the same files in server/. Generated images are not in the state folder, see Outside the state folder.

The database #

The database is one SQLite file, copilot.db. The relay creates it on first start. It holds what you would call your data:

• conversations and their messages, with the transcript, attachments' index and pinned messages
• the message queue, queued and waiting messages, and questions an agent asked
• the relay's settings that you change in the web UI (the app-wide switches, provider settings, retention choice, update preferences, the model lists)
• the OpenAI, Cursor and Added in 0.9.17 DeepSeek API keys, if you entered them
• paired relays and their tokens, and the subscriptions that watch sessions on this and on paired relays
• the web-push subscriptions of your devices and the relay's push keys
• shared-conversation links
• sub-agent and workflow records, activity and thoughts per conversation
• the index of uploaded files and which messages use them
• usage snapshots for the plan meters (Check Usage), and Added in 0.9.17 what the DeepSeek card counts: the tokens and searches of DeepSeek turns per model and per day, the last totals each DeepSeek session reported, and the balance readings its bar is measured against
• image chats: their operations and the links between generated images
• preview cards

Migrations run by themselves every time the relay starts. They create what is missing and add columns, and running them again changes nothing. You do not run them and cannot skip them.

Backing up #

OAR has no backup command. The database runs in SQLite's write-ahead mode, so recent changes can sit in the -wal file next to it. To back it up:

1. Stop the relay with oar stop.
2. Copy copilot.db and, if they exist, copilot.db-wal and copilot.db-shm together.
3. Start the relay again.

To restore, stop the relay and put the copied files back as they were. Do not copy copilot.db alone while the relay runs, and do not mix a database file with the -wal file of another copy. A backup contains your API keys and tokens, see Where secrets live; keep it as private as the state folder.

Logs #

The Copilot extension engine has no worker log: it is the Copilot CLI's own terminal. A relay run as a systemd service also writes to the journal, see Start the relay automatically.

A git checkout started with npm start keeps its logs in server/logs. One started with oar start or oar copilot keeps them in ~/.config/copilot-remote/logs (Windows: %LOCALAPPDATA%\copilot-remote\logs), unless COPILOT_WEB_RELAY_LOG_DIR names another folder.

Where secrets live #

While a worker starts under tmux, the relay writes its provider key (the OpenAI, Cursor or Added in 0.9.17 DeepSeek key, or a CLAUDE_CODE_OAUTH_TOKEN from the relay's environment for a Claude Cloud or, Added in 0.9.17, a Claude worker) to a temporary file in the system's temp folder, readable by you only. The worker's shell reads it once and deletes it. Each worker gets only its own provider's key.

Retention #

The relay removes these by itself. Nothing else is deleted unless you delete a conversation.

Deleting a conversation removes its messages, queue entries, questions and sub-agent records from the database, and the Claude transcript and the generated images belonging to it. Added in 0.9.17 For a DeepSeek conversation it also removes, in data/deepseek-claude/, the transcript, the session's folders, what its stopped Claude Code left (its registration, hook environment and shell snapshot) and the project folder once no other session uses it, and from the database the last totals its sessions reported. What it added to the DeepSeek card's totals and days stays. What each provider keeps itself is in the next section.

Outside the state folder #

Before 0.9.14 the Cursor stores sat in server/data/cursor-agents inside the package folder by default, which an update replaces, so a conversation could lose its stored agent and get a new one (see Cursor). A conversation whose store is still at that old place keeps using it there, and one with a store in both places uses the one changed last; nothing is moved or deleted.

Your agents' work, the files in your project folders, is outside OAR's storage entirely.

One relay per data folder #

The relay creates relay-server.lock in the data folder when it starts and removes it when it stops. The file holds the relay's process number, a hash of its token and its start time.

If a second relay starts on the same data folder while the first one runs, the second one prints one line and exits, Added in 0.9.14 with code 78 (code 1 before), which the Linux service does not retry:

Relay already running (pid=4242, startedAt=2026-01-05T09:12:40.000Z; lock /home/dev/.oar/data/relay-server.lock). It is held by relay process 4242: oar stop, or end process 4242.

Relay appears to be owned by another live process instead of Relay already running means the running relay has another token. When the holder cannot be told to be a relay, the hint reads If no relay is running, end process 4242 or delete the lock. oar start prints the same hint after The relay did not come up. The first relay is not touched. Messages stay pending when the relay you expected is not the one that runs; oar doctor shows the config and database in use.

After a crash or a power loss the lock file is left behind. Added in 0.9.14 A lock from before the last boot, or whose process number now belongs to a process started after it, is stale: the next start moves it aside, logs Recovered stale singleton lock, and takes the lock over. This no longer goes by the clock, so a clock step does not make a running relay look gone, and two starts recovering the same lock do not both run. A lock that cannot be read (an empty one a power loss left) is read again and counts as held unless its time is more than 10 seconds off. oar start no longer removes a lock this version wrote; it still removes one of an earlier version when nothing answers on the relay's port.

Two relays can run side by side when they have separate data folders and ports. See The oar command for how oar finds the relay, and Restarts and resume for what a restart keeps.