# Configuration

Standalone reuses the shared `~/.adhdev/` data directory, but the important part for self-hosted users is local runtime behavior, not cloud auth.

## Config Files

Shared daemon settings live in:

```text
~/.adhdev/config.json
```

Runtime state such as recent activity and saved session metadata lives in:

```text
~/.adhdev/state.json
```

Standalone network/font preferences live in:

```text
~/.adhdev/standalone-network.json
```

Saved chat-history rollups used by the saved-history launcher live under:

```text
~/.adhdev/history/
```

Session-host runtime data is stored separately under:

```text
~/.adhdev/session-host/adhdev-standalone/
```

Terminal mux state is stored separately under:

```text
~/.adhdev/terminal-mux/
```

## Fields That Matter For Standalone

The standalone UI and local daemon primarily care about fields like these:

```json
{
  "machineNickname": "Studio Mac",
  "workspaces": [
    {
      "id": "ws_example",
      "label": "remote_vs",
      "path": "~/Work/remote_vs",
      "addedAt": 1710000000000
    }
  ],
  "defaultWorkspaceId": "ws_example",
  "providerSettings": {},
  "ideSettings": {},
  "providerSourceMode": "normal",
  "providerDir": "~/Work/adhdev-providers",
  "terminalSizingMode": "measured"
}
```

Relevant standalone-facing fields:

| Field | Meaning |
|-------|---------|
| `machineNickname` | Friendly name shown in the dashboard |
| `workspaces` | Saved launch targets for IDE, CLI, and ACP launches |
| `defaultWorkspaceId` | Default saved workspace selection |
| `providerSettings` | Per-provider user settings, including machine-local CLI/ACP activation and executable overrides |
| `ideSettings` | Per-IDE extension enablement settings |
| `providerSourceMode` | Provider source policy: `normal` (upstream cache + overrides) or `no-upstream` (skip upstream fetch/load) |
| `providerDir` | Optional explicit override root. Set this if you want a local `adhdev-providers` checkout to shadow upstream providers. Apply/reload provider source config after changing it. |
| `terminalSizingMode` | `measured` by default, or `fit` for the legacy xterm fit path |

Standalone-only preferences stored outside `config.json`:

| File / field | Meaning |
|-------------|---------|
| `~/.adhdev/standalone-network.json` → `standaloneBindHost` | Saved default bind host for future standalone launches |
| `~/.adhdev/standalone-network.json` → `standaloneFontPreferences.chat` | Standalone chat/prose font override |
| `~/.adhdev/standalone-network.json` → `standaloneFontPreferences.code` | Standalone markdown/code/preformatted font override |
| `~/.adhdev/standalone-network.json` → `standaloneFontPreferences.terminal` | Standalone terminal/tool-row font override |

## Practical Self-hosted Settings

If you only care about the settings that most affect day-to-day standalone behavior, focus on these:

- `machineNickname` so the dashboard shows a meaningful machine label
- `workspaces` and `defaultWorkspaceId` so launch flows start in the right places
- `providerSettings` for per-provider behavior, machine-local CLI/ACP activation, executable paths, and auth-related settings
- `providerSourceMode` if you want to keep local user overrides but disable upstream fetch/load on this machine
- `providerDir` if you want ADHDev to use an explicit local provider override root instead of the default `~/.adhdev/providers`; use the dashboard's Providers tab **Apply + Reload** flow after changing provider source settings
- `terminalSizingMode` if terminal rendering behaves poorly in your environment

## Shared Fields You Can Usually Ignore

`config.json` is shared between standalone and cloud-capable codepaths, so you may also see fields such as:

- `serverUrl`
- `allowServerApiProxy`
- `userEmail`
- `userName`
- `machineSecret`
- `registeredMachineId`
- `setupCompleted`

Those are not required to run standalone locally. They only matter if the same machine also participates in the cloud flow.

## Runtime State vs Static Config

A useful rule:

- `config.json` is for durable user intent
- `state.json` is for runtime-oriented state
- `session-host/` is for hosted runtime recovery under the standalone session-host namespace
- `terminal-mux/` is for local mux workspace persistence

This distinction matters when you are debugging local state drift. Not every runtime symptom should send you back to `config.json`.

## Authentication For Standalone

This page is the canonical reference for standalone auth, saved network defaults, and standalone-only font preferences.

Standalone now supports two self-hosted auth patterns:

1. `--token` / `ADHDEV_TOKEN` for operator-style API or URL-token access
2. a dashboard-managed password for browser sessions

Use them for different jobs:

| Option | Best for | What the user sees |
|--------|----------|--------------------|
| token auth | scripts, curl, automation, opening the dashboard with an explicit token | requests must include the token; no interactive browser password prompt is required |
| dashboard password | normal browser use on a local/LAN dashboard | the dashboard shows a password prompt and then uses a local session cookie |
| both enabled | mixed browser + automation setups | browser users can sign in with the password while scripts can keep using the token |

Token auth remains process-scoped.

```bash
adhdev standalone --token mysecret
```

```bash
ADHDEV_TOKEN=*** adhdev-standalone
```

If you open the dashboard without a configured password, you can set one from:

- `Settings` → `Dashboard Security`

You can also choose the default network bind mode from:

- `Settings` → `Network Access`

Standalone-only font customization lives here:

- `Settings` → `Appearance` → `Fonts`

That section lets you save separate font stacks for:

- chat text
- markdown code / preformatted output
- terminal transcript cards and tool rows

Those font overrides apply only to the standalone dashboard. They do not affect the cloud dashboard.

That setting controls whether future standalone launches default to localhost-only or all-interfaces bind mode, without requiring `--host` every time.

Practical meaning:

- `127.0.0.1` / localhost-only = only this machine can open the dashboard
- `0.0.0.0` / all interfaces = other devices on the same LAN can also open it
- if you save `0.0.0.0` and do not configure token auth or a dashboard password, standalone warns because the dashboard is exposed to the LAN without protection

The standalone password, saved bind-host preference, and standalone font overrides are stored only in local standalone state under `~/.adhdev/` and are not part of cloud auth.

When standalone is bound to `0.0.0.0` without either token auth or password auth, startup logs and the dashboard settings page show a warning because anyone on the same LAN can open the dashboard until auth is enabled.

## CLI Flags vs Environment Variables

For normal self-hosted use, prefer CLI flags over environment variables.

Documented standalone runtime inputs:

| Input | Meaning |
|-------|---------|
| `--port` | HTTP and WebSocket port |
| `--host` | Bind to `0.0.0.0` for LAN access |
| `--token` | Require dashboard/API token auth |
| `--no-open` | Skip automatic browser open |
| `ADHDEV_TOKEN` | Token auth fallback when no `--token` flag is passed |
| `ADHDEV_SESSION_HOST_NAME` | Override the standalone session-host namespace (default: `adhdev-standalone`) |
| `ADHDEV_RESTORE_HOSTED_SESSIONS_ON_STARTUP` | Opt into restoring hosted runtimes on startup; ordinary standalone launch stays fresh by default |

## Logs

Local logs are stored in:

```text
~/.adhdev/logs/
```

They are also printed to stdout when the standalone server runs in the foreground.

## Related Local State

If you are operating self-hosted seriously, these other local state areas are worth knowing:

- `~/.adhdev/session-host/adhdev-standalone/runtimes/` for hosted runtime snapshots
- `~/.adhdev/history/` for saved chat-history rollups and the saved-history index
- `~/.adhdev/standalone-network.json` for saved bind-host and standalone font preferences
- `~/.adhdev/terminal-mux/workspaces/` for mux workspace layouts
- `~/.adhdev/terminal-mux/state.json` for last-workspace client state

## Provider Directories

The dashboard's machine **Providers** tab shows the effective user root, upstream root, and provider root order. Its **Apply + Reload** action refreshes provider resolution for fix/verify flows and new launches. Existing running sessions may still need a restart to use changed provider scripts.

CLI and ACP providers are machine-scoped: enable the provider, run detection, and set custom executable path/args if needed before expecting it to appear as launchable.

Provider roots use a category-based layout:

- `~/.adhdev/providers/<category>/<type>/` for local overrides and user providers
- `~/.adhdev/providers/.upstream/<category>/<type>/` for downloaded upstream providers
- bundled providers ship with the same `category/type` layout inside the installed packages

## Repo Mesh Refinery Submodule Publishing

Refinery requires every submodule gitlink in the refined root tree to be reachable from that submodule's configured `origin/main`. By default, an unreachable submodule commit keeps convergence in `blocked_review` and asks for explicit approval before anything is published.

Repositories that intentionally use submodule gitlinks as part of the same delivery flow can opt in with:

```json
{
  "version": 1,
  "allowAutoPublishSubmoduleMainCommits": true,
  "validation": {
    "required": true,
    "commands": [
      { "command": "npm", "args": ["run", "typecheck"], "category": "typecheck" },
      { "command": "npm", "args": ["run", "test"], "category": "test" }
    ]
  }
}
```

Save that as `.adhdev/refine.json`, `.adhdev/repo-mesh-refine.json`, or another supported repo mesh/refine config path. Mesh policy can also set `allowAutoPublishSubmoduleMainCommits: true`.

The opt-in is narrow: Refinery only considers submodule commits already referenced by the root gitlinks being refined, only after validation and patch-equivalence pass, and only pushes a non-force `<commit>:refs/heads/main` refspec to the submodule `origin`. It then fetches and verifies that the commit is an ancestor of `origin/main`. Refinery does not push root `main`, force push, rewrite history, or publish arbitrary submodule commits. If publishing or verification fails, the refine result stays `blocked_review` with the submodule path, commit, remote, branch, refspec, and error evidence.

## Repo Mesh With Hermes Agent

Hermes Agent can use self-hosted Repo Mesh tools through ADHDev's MCP server, but Hermes does not auto-import repo-local `.mcp.json`. For Hermes, add a YAML entry to the Hermes config under `mcp_servers`, then start a fresh Hermes session.

Find the Hermes config path:

```bash
hermes config path
```

Add the selected mesh id from the standalone Repo Mesh page:

```yaml
mcp_servers:
  adhdev-mesh:
    command: adhdev-mcp
    args:
      - --repo-mesh
      - mesh_abc123
    enabled: true
```

After saving the config, exit and relaunch Hermes. MCP servers are discovered at Hermes session startup, so an already-running session may not see the new `adhdev-mesh` tools.

In the standalone dashboard, the Repo Mesh detail page shows this Hermes-specific YAML only when the Hermes provider declares manual MCP setup. It does not show Claude-style `.mcp.json` config there because Claude-style clients can use their own auto-import/config flow.

## Related Pages

- [Self-hosted Setup](setup.md)
- [Session Host](session-host.md)
- [Terminal Mux](terminal-mux.md)
- [Local API](local-api.md)