# Understand Oysterun Config Files

Use this page when you need to know where Oysterun stores Host settings,
debug-only options, Cloud identity, and Agent Folder settings. It helps you
choose the right visible product surface before editing files directly.

The page path keeps the historical spelling `config_hierachy.md`.

## Prerequisites

- Oysterun is installed.
- You can open the Oysterun dashboard and sign in if the login screen appears.
- You can identify which Host you are using before inspecting files.
- You have filesystem access only when you intentionally inspect local config
  files outside the UI.

Starting screen: the Oysterun dashboard after sign-in. Use the visible menu for
Host Preferences, the **Sessions** page for Session Setup, an open Chat screen
for Session Profile, and the **Explorer** tab or chat folder button for
Explorer.

## Start From The Dashboard

1. Open the dashboard menu and choose **Host Preferences**.

   Checkpoint: the Host Preferences page opens. Use it for Host-level settings
   such as provider command paths, Browse Root, display name, notification
   sound preferences, Website access, and Host connection information.

2. To reach **Session Setup**, choose **Sessions**, then choose **New Session**
   or the visible setup action for the Session you are creating or resuming.

   Checkpoint: the Session Setup page opens and shows launch fields such as
   **Start Folder**, **Agent ID**, **Session Name**, and **Provider**.

3. To reach **Session Profile**, open the intended Session from **Sessions** so
   its Chat screen is visible, then use the top-bar **Open Session Profile**
   control.

   Checkpoint: Session Profile opens for that same Session and shows the
   selected folder and live-session settings.

4. To reach **Explorer**, choose the bottom **Explorer** tab for the current
   Browse Root, or open a Session chat and choose its top-bar folder button to
   browse files for that Session.

   Checkpoint: Explorer opens with folder rows and breadcrumbs for the selected
   Browse Root or Session folder.

Expected result: normal user settings are changed through visible Oysterun
controls instead of hand-editing runtime files.

## Identify The Host Config Directory

Before a task asks you to inspect the Host config directory, identify the Host
first:

1. Open **Host Preferences** from the dashboard menu.
2. Check the visible Host connection information and Browse Root so you know
   which running Host the page represents.
3. If a support or verification task gave you `OYSTERUN_CONFIG_DIR`, use that
   exact directory for this Host. If it did not, use the normal user config
   directory `~/.oysterun` for the account running Oysterun.

Checkpoint: you can say which Host you are inspecting and whether its config
directory came from `OYSTERUN_CONFIG_DIR` or from the default `~/.oysterun`
location. Do not open or copy config files until this identity matches the Host
you intended.

## Use The Product UI First

1. Use **Host Preferences** for Host-level settings such as provider command
   paths, Browse Root, display name, notification sound preferences, Website
   access, and Host connection information.
2. Use **Session Setup** or **Session Profile** for Session-specific defaults
   and Agent Folder settings.
3. Use Explorer when you need to inspect folders from the selected Browse Root.

Expected result: you can match the setting to its visible product surface
before deciding whether direct file inspection is still necessary.

## Host Config Directory

Oysterun chooses the Host config directory from `OYSTERUN_CONFIG_DIR`. If that
environment variable is not set, the normal user config directory is
`~/.oysterun`.

The Host config directory can contain:

| File or folder | What it is for | User action |
| --- | --- | --- |
| `config.json` | Product runtime settings and Host Preferences values. | Prefer setup or Host Preferences. |
| `config.debug.json` | Optional debug-only switches. | Use only when a support or verification task explicitly asks for it. |
| `config.dev.json` | Browser verification login source for test stacks. | Not a product runtime file. |
| `cloud_identity.json` | Host Cloud identity and credentials. | Do not hand-edit; use Cloud or Host Preferences status flows. |
| `params.json` | Current provider model/status catalog. | Do not hand-edit. |
| `service-control-token.json` | Local service-control token for loopback service commands. | Do not copy into prompts or product config. |
| `session-history.json` | Session index and resume metadata. | Use Sessions UI or CLI commands instead of direct edits. |
| Matrix and media storage folders | Product chat, media, and Matrix runtime data. | Do not delete or hand-edit as a primary fix. |

Checkpoint: you can identify whether a setting belongs in Host Preferences,
Session Setup/Profile, a debug-only file, Cloud identity, or Agent Folder
config before changing anything.

## Host Runtime Settings

`config.json` is the main Host runtime settings file. It can contain values
such as:

```text
port
direct_host_url
public_base_url
connection_mode
dashboard_user
dashboard_password_hash
claude_command
codex_command
default_browse_path
show_hidden_files
notification_sound_web_enabled
notification_sound_app_enabled
display_name
session_defaults
```

Plaintext dashboard passwords do not belong in `config.json`. Cloud device
credentials and Cloud registration state belong in `cloud_identity.json`, not
in `config.json`.

When **Show hidden files** is enabled, Explorer shows hidden folders in the
selected Browse Root. A visible checkpoint is that hidden folders such as
`.claude` and `.oysterun` appear as normal Explorer rows.

![Explorer showing hidden .claude and .oysterun folders with private path breadcrumbs mosaiced.](assets/p121/f07/p121-f07-explorer-hidden-entries-masked.png)

## Debug And Verification Files

`config.debug.json` is optional. If it is missing, Oysterun uses safe defaults
and normal startup should not create it. Debug-only settings can reveal
verification controls or providers that normal users do not see.

The public product intentionally hides beta installation controls. For an
explicitly authorized development verification only,
`debug_host_preferences_beta_update_enabled` enables the debug-only Beta check
and install controls in Host Preferences. Do not set that flag to advertise a
public-user feature, and do not treat its default absence as a product defect.

`config.dev.json` is for worker/browser verification login setup in test
stacks. Product Host runtime login reads `config.json`, not `config.dev.json`.
Do not use `config.dev.json` as a product setting source.

Expected result: normal product settings stay in `config.json`, debug switches
stay in `config.debug.json`, and verification-only login material stays out of
product runtime config.

## Agent Folder Settings

Shared Agent Folder settings belong in:

```text
<agent_folder>/.oysterun/config.json
```

Private or local Agent Folder settings belong in:

```text
<agent_folder>/.oysterun/local.json
```

`.codex/config.json` is not an Oysterun Route C Session config source. No
current Oysterun Route C product config layer is named `.security`.

## Cloud Identity

Cloud identity belongs in:

```text
<host_config_dir>/cloud_identity.json
```

This file can hold Cloud device identity, credential, registration, and
onboarding state. Host Preferences may show Cloud status, but users should not
copy Cloud credentials into prompts, public docs, product config, or Agent
Folder config.

## If Config Recovery Is Unavailable

Bounded recovery:

1. Use Host Preferences, Session Setup, Session Profile, or the Oysterun CLI
   before editing files directly.
2. If the wrong Host is being inspected, return to the dashboard, open Host
   Preferences from the menu, and compare the visible Host connection
   information with `OYSTERUN_CONFIG_DIR` or the default `~/.oysterun` path.
3. If a normal setting is missing, set it through the visible UI when possible.
4. If a debug-only control is missing, check whether a support or verification
   task explicitly enabled it in `config.debug.json`.
5. If a Cloud identity problem appears, use the visible Cloud or Host
   Preferences status flow instead of hand-editing `cloud_identity.json`.
6. If chat or media storage appears damaged, stop direct edits and use the
   product recovery path or support guidance for that exact Host.
7. If a file contains tokens, credentials, local paths, or private chat data,
   do not paste it into public messages.