CodeNomad/docs/help/en/server.md

Standalone server

Run CodeNomad where your projects and tools live, then use its browser UI locally or remotely. The backend supplies filesystem access, Git operations, authentication and event delivery. OpenCode's shared service owns conversations and execution; it is not a child server to stop when a browser disconnects.

The same UI supports multiple project tabs and worktrees, conversation families and background activity, bounded history loading, search and timeline navigation, and a command palette and shortcuts. Browser and tablet access do not move execution off the host.

Prepare the host

1. Install Node.js 24 LTS and npm; the repository's pinned build runtime is 24.20.0. Desktop packages include Node/npm.
2. Put Git on the backend process's PATH. Git inside WSL alone does not satisfy a Windows backend.
3. Install or select OpenCode: the required minimum is 2.1.0, with 2.1.0 the recommended qualification target. Newer or custom builds undergo compatibility checks, not a tested-version allowlist. See OpenCode setup.
4. Choose the folder from which to start the server, or pass --workspace-root explicitly.

Without Git, conversations remain available only in the explicitly opened physical folder; Git and worktree operations fail. Install Git and restart the backend after a PATH change. A workspace root limits opening/browsing, not agent execution: see Security.

Run or install

Choose one installation method. These first-run examples use a local bootstrap rather than putting a password into shell history:

Run with npx

npx @neuralnomads/codenomad --generate-token --launch

Install globally

npm install -g @neuralnomads/codenomad
codenomad --generate-token --launch

Install in a project

npm install @neuralnomads/codenomad
npx codenomad --generate-token --launch

npx codenomad uses the project's installed binary when present. This installs the package in that project; it does not make configuration or OpenCode storage project-local.

1. Open the printed Local Connection URL on the host. Complete local bootstrap, then save a persistent server password. That procedure includes a loopback-only HTTP setup option if you have not configured HTTPS trust yet.
2. On subsequent starts, omit --generate-token; alternatively supply CODENOMAD_SERVER_PASSWORD on every start.
3. Use codenomad --help to inspect the installed CLI's options.

The commands run in the foreground. Closing the terminal or sending Ctrl+C stops that backend and its Remote Control connection. --launch only opens a browser; it does not daemonize the server. For unattended availability, run the same command under your OS process/service manager with explicit configuration, working directory, environment and restart policy. Do not put secrets in service logs or a public unit file.

Closing a browser does not stop a separately running standalone backend. Closing a project tab removes that project's CodeNomad connection, but sessions continue in OpenCode; reopen the project to find them again. CodeNomad never unloads its native Location. Closing a whole window, quitting or reloading preserves project connections for restoration. Backend shutdown likewise leaves the OpenCode service running. Backend-dependent features are unavailable until CodeNomad returns; see Missions for the separate native scheduling lifetime.

Addresses and ports

Startup prints Local Connection URL, and Remote Connection URL when one is available, plus Other Accessible URLs where applicable. Use the printed scheme and port, not a guessed address. A loopback URL is reachable only on that machine; a printed LAN address still requires routing and firewall access.

HTTPS prefers port 9898 and HTTP prefers 9899. With no port override, an occupied preferred port falls back to an OS-assigned port. An explicit nonzero port does not fall back; 0 requests an OS-assigned port. Ports accept integers from 0 through 65535.

For listener exposure, certificates, VPN/SSH and reverse proxies, use Direct remote access. For access without an inbound port, use Remote Control.

Public CLI reference

Flags override their environment counterparts. Value-taking flags use the shown argument; switches do not. HTTPS/HTTP values recognize 1, true, yes, y and on as enabled, case-insensitively; use explicit true/false for clarity. UI auto-update recognizes 1, true and yes.

Strict boolean environment variables (CLI_UNRESTRICTED_ROOT, CLI_UI_NO_UPDATE, CLI_LAUNCH, CODENOMAD_GENERATE_TOKEN and CODENOMAD_SKIP_AUTH) enable their switches with 1, true, yes or on, ignoring case and surrounding whitespace. 0, false, no, off, empty/whitespace-only values or unset variables leave the switches off. Any other value prevents server startup, even with the corresponding CLI flag. A CLI flag enables its switch over a valid off value; otherwise, the false defaults below apply.

Flag	Environment	Default and effect
-h, --help	—	Print help and exit.
-v, --version	—	Print the installed package version and exit.
--host <host>	CLI_HOST	127.0.0.1; localhost normalizes to IPv4 loopback. IPv6 zone identifiers are rejected. See the binding matrix.
--https <enabled>	CLI_HTTPS	true; HTTPS listener.
--http <enabled>	CLI_HTTP	false; HTTP listener. At least one listener must be enabled.
--https-port <number>	CLI_HTTPS_PORT	9898 preferred; 0 automatic.
--http-port <number>	CLI_HTTP_PORT	9899 preferred; 0 automatic.
--tls-key <path>	CLI_TLS_KEY	Unset; PEM private key, requires --tls-cert.
--tls-cert <path>	CLI_TLS_CERT	Unset; PEM certificate, requires --tls-key.
--tls-ca <path>	CLI_TLS_CA	Unset; optional PEM CA chain for supplied certificates.
--tlsSANs <list>	CLI_TLS_SANS	Unset; additional comma-separated DNS names/IPs for generated certificates.
--workspace-root <path>	CLI_WORKSPACE_ROOT	Process working directory; root for opening workspaces.
--unrestricted-root	CLI_UNRESTRICTED_ROOT	false; allow full-filesystem browsing. Not an agent sandbox setting.
--config <path>	CLI_CONFIG	Resolved active default: ~/.config/codenomad/config.yaml. Accepts a directory or YAML file for explicit placement.
--log-level <level>	CLI_LOG_LEVEL	info; documented levels: trace, debug, info, warn, error.
--log-destination <path>	CLI_LOG_DESTINATION	stdout; otherwise write to the chosen file.
--username <username>	CODENOMAD_SERVER_USERNAME	codenomad; runtime auth username. A stored auth file retains its stored username when no runtime password overrides it.
--password <password>	CODENOMAD_SERVER_PASSWORD	Unset; runtime-only password, takes precedence over the managed auth file.
--auth-cookie-name <name>	CODENOMAD_AUTH_COOKIE_NAME	codenomad_session; characters outside letters, digits, _ and - become _.
--generate-token	CODENOMAD_GENERATE_TOKEN	false; print a one-use, 60-second local bootstrap token.
--dangerously-skip-auth	CODENOMAD_SKIP_AUTH	false; disables direct-listener authentication. Dangerous: see Security. Remote Control still requires device pairing.
--ui-dir <path>	CLI_UI_DIR	Package's public directory; an explicit override serves that UI instead of remote UI resolution.
--ui-dev-server <url>	CLI_UI_DEV_SERVER	Unset; proxy UI through the HTTP listener. For development, use --https=false --http=true; the HTTPS listener does not proxy the dev UI.
--ui-no-update	CLI_UI_NO_UPDATE	false; overrides auto-update and uses available cached/bundled UI.
--ui-auto-update <enabled>	CLI_UI_AUTO_UPDATE	true; check for compatible remote UI at startup.
--ui-manifest-url <url>	CLI_UI_MANIFEST_URL	https://ui.codenomad.neuralnomads.ai/version.json; remote UI manifest.
--launch	CLI_LAUNCH	false; open the local UI in a browser after startup.
--upgrade [version]	—	No upgrade by default. When requested, globally install @neuralnomads/codenomad@latest, or the supplied version, and exit.

The public reference lists user-facing options; desktop hosts manage their own private launch coordination.

Additional deployment environment

Variable	Default and scope
CODENOMAD_GITHUB_REPO	NeuralNomadsAI/CodeNomad; repository queried for release offers.
CODENOMAD_REMOTE_CONTROL_API	Unset: hosted OpenTunnel API. Set an API origin for a self-hosted relay deployment.
NODE_EXTRA_CA_CERTS	Node's optional additional CA file; passed with allowed startup environment when starting a missing OpenCode daemon. Does not change an already running daemon.

Provider-specific usage credentials are covered in Providers. Desktop data-profile selection is covered in Desktop, not controlled by the release feed.

Configuration and storage ownership

Default paths below use the backend user's home. An explicit --config directory changes the configuration base; a YAML filename selects that file with sibling state/storage. Use one intentional configuration identity for a deployment and protect the whole directory with OS permissions.

Owner/data	Default location or rule
Stable CodeNomad preferences	~/.config/codenomad/config.yaml
Mutable CodeNomad state	~/.config/codenomad/state.yaml
CodeNomad instance metadata	~/.config/codenomad/instances/
Password hash	auth.json beside the active YAML configuration; app-managed.
Generated TLS certificates and private keys	tls/ under the configuration base.
Remote Control route, enabled choice and device hashes	remote-control-devices.json under the configuration base.
Temporary workspace registry and folders	temporary-workspaces.json and temporary-workspaces/ under that base.
Installed panel extensions and permission receipts	panel-extensions/ and permission-receipts/ under that base.
Downloaded UI cache	~/.config/codenomad/ui/; the CLI's UI resolver uses this home-based cache even with a custom --config.
OpenCode conversations, messages, service registration and provider connections	OpenCode's own global storage on the execution host, not the CodeNomad instance directory.
Desktop restore state	Default ~/.codenomad/client-state/v2/; see Desktop for profile/window scope.

CodeNomad connects to the existing shared daemon or starts it if missing. Startup environment affects a newly started daemon only. Separately, the configured complete session environment is applied before each prompt, custom command or session shell request, not when preferences are merely viewed or edited. See OpenCode setup.

Events and reconnects

The backend consumes a shared native OpenCode event stream and multiplexes workspace and CodeNomad events to browser clients using Server-Sent Events. Delivery is live and volatile: there is no guaranteed event replay.

After reconnecting, the UI refetches authoritative session and pending-request state; file/configuration invalidations also trigger fresh reads. A reconnect is not permission to repeat a send, delete, answer or other mutation whose reply was lost. Check the resulting state first. Known pending requests and drafts are retained when recovery is incomplete; see Permissions and Troubleshooting.

Preview packages and maintenance

To try the preview CLI package explicitly:

npx @neuralnomads/codenomad-dev --generate-token --launch

Use a deliberately separate configuration if you need isolated CodeNomad settings; selecting a package does not isolate shared OpenCode storage. Settings → Info → Updates → Update feed controls offered releases, not the backend's data identity or the installed package.

codenomad --upgrade updates the global stable CLI package using the detected npm/pnpm/bun manager (npm if none is detected). It neither restarts a running server nor updates OpenCode. For a project-local or preview installation, update that exact npm package explicitly. Restart your managed CodeNomad process deliberately after updating; check its printed addresses again.

See Updates for desktop maintenance, Support for source-build commands, and Providers for provider plan usage.