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:

~/.adhdev/config.json

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

~/.adhdev/state.json

Standalone network/font preferences live in:

~/.adhdev/standalone-network.json

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

~/.adhdev/history/

Session-host runtime data is stored separately under:

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

Terminal mux state is stored separately under:

~/.adhdev/terminal-mux/

Fields That Matter For Standalone

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

{
  "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.

adhdev standalone --token mysecret

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:

~/.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:

{
  "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:

hermes config path

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

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
• Session Host
• Terminal Mux
• Local API