CodeNomad: a desktop cockpit for OpenCode sessions

The gap CodeNomad is trying to fill

OpenCode is a terminal tool. That is fine for a short prompt and awkward for a session you keep open for six hours across three repositories. CodeNomad's own framing is blunt about the division of labour: "OpenCode gives you the engine. CodeNomad gives you the cockpit." The project does not ship a model or an agent loop. It is a shell around a CLI you already have, and the README lists the OpenCode CLI as a hard requirement that "must be installed and in your PATH".

The audience follows from that. This is for developers who already chose OpenCode and now want window management, session history, git worktrees and a browser tab that survives being away from the desk. If you have not adopted OpenCode, CodeNomad has nothing to offer you yet, because there is no bundled fallback engine.

Architecture: a server, two desktop shells, one SolidJS UI

The repository is an npm workspaces monorepo with four packages, and the split tells you where the real logic lives. packages/server holds "Core logic and CLI": workspaces, an OpenCode proxy, the API, authentication and speech. packages/ui is the SolidJS frontend. packages/electron-app and packages/tauri-app are two desktop shells that manage processes, IPC and native dialogs.

That means the desktop app is not a separate product from the browser experience. Both talk to the same server, which proxies to OpenCode. The Tauri package is described as experimental in the README's package table, and the release notes only ever publish dev-tagged builds, so the Electron path is the one with more mileage behind it.

SideCars are the most interesting piece of the design. They mount a local web tool under /sidecars/:id, and the README is specific about how origins are handled: loopback HTTP previews get a dedicated .preview.localhost origin so root routes, POSTs and live reload behave normally, while HTTPS, LAN and web hosts fall back to a capability path with token-scoped URLs in opaque-origin sandboxes. That is a deliberate trade-off. Local tools get fidelity; remote ones get isolation, and the two do not behave identically.

Installing CodeNomad and opening a first session

There are two entry points. Desktop installers are published per platform: macOS gets DMG and universal ZIP, Windows gets an NSIS installer plus x64 and ARM64 ZIPs, and Linux gets a Tauri deb plus an Electron portable tar.gz for x64. The README notes the Tauri deb is built and installation-tested on Ubuntu 24.04 and that compatibility with older Debian-based distributions is not guaranteed.

The server route needs Node.js 18+ and is a single npx command. The password is mandatory on first run and can come from the flag, the environment variable, or an auth.json file:

npx @neuralnomads/codenomad --password <your-password> --launch

HTTPS is on by default with a self-signed certificate, so the browser will warn you. The README says this is expected and tells you to continue through the advanced prompt. If you want to avoid the warning on a local-only machine, disable HTTPS and enable HTTP instead:

npx @neuralnomads/codenomad --password <your-password> --launch --https=false --http=true

There is a separate dev channel published from the dev branch, which is what the release list reflects:

npx @neuralnomads/codenomad-dev --password <your-password> --launch

To run from source, the README gives the standard monorepo sequence. npm run dev resolves to the Electron workspace script, so this starts the desktop shell rather than the server:

git clone https://github.com/NeuralNomadsAI/CodeNomad.git
cd CodeNomad
npm install
npm run dev

Once the workspace is open, adding a SideCar means supplying four fields: a display name, a port pointing at a local HTTP or HTTPS service on 127.0.0.1, a base path mounted under /sidecars/:id, and a prefix mode. The README's ttyd example uses port 7681 with strip prefix, which removes /sidecars/terminal before forwarding upstream.

Where CodeNomad gets in your way

The release history is the first problem. Every published version is a v0.20.0-dev build dated 2026-09-19, and the default branch is dev. There is no stable tag in the release list. If your team pins dependencies or needs a changelog you can reason about before upgrading, this is not that project yet.

The second issue is the dependency on OpenCode itself. CodeNomad is a proxy and a UI, so anything OpenCode cannot do, CodeNomad cannot do either. When the CLI changes its interface, the proxy has to follow, and the README does not document how that compatibility is tracked.

Third, the self-signed certificate is a real friction point for remote access. The README's instruction to click through a browser warning is reasonable for a laptop on a home network and much less reasonable if you are exposing the server to a team. The top-level README defers TLS details to packages/server/README.md, so the flags that matter for a serious deployment are not on the front page.

Finally, SideCar prefix behaviour is a footgun. A tool that needs its own root routes must use preserve prefix, while one that expects to be mounted at the root must use strip prefix. Choosing wrong produces broken asset paths, not an error message.

CodeNomad versus running OpenCode in a terminal or over SSH

The honest alternative is OpenCode itself, used the way it ships. You get the same engine, no extra process, no password to manage and no self-signed certificate. What you lose is everything CodeNomad adds: multiple concurrent instances in one window, session history you can return to, git worktrees, voice input, a file browser and a command palette.

A second alternative is a generic remote development setup, such as opening a terminal multiplexer over SSH and running OpenCode there. That keeps your existing tooling and avoids a new web surface entirely. The difference in approach is that CodeNomad is a stateful application with its own server, auth layer and preview proxy, whereas a multiplexer is a transport. If your requirement is simply "reach my session from another machine", the multiplexer is less machinery. If your requirement is "manage several sessions across several repositories with a UI", CodeNomad is the thing that actually addresses it.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-20. The release cadence visible in the release list is dense: three v0.20.0-dev builds on 2026-09-19 alone. That pattern is consistent with active work on the dev branch, and it is also the reason upgrades carry risk. Dev-tagged builds can change behaviour between two releases published an hour apart.

The workspace version is 0.20.0-dev-v2, and the repository carries a MIGRATION_V2.md file alongside DESKTOP_V2_COMPARISON.md, which suggests the project has already gone through at least one breaking migration. Anyone adopting this should read MIGRATION_V2.md before assuming an upgrade is a drop-in.

The licence is MIT, declared both in the repository and in the workspace package.json. That is permissive and places few obligations on how you redistribute or modify it. It also means no warranty, and with a project at this stage the practical exposure is that you may be maintaining a fork of a moving target. THIRD_PARTY_NOTICES.md exists in the repository root, so bundled dependencies carry their own terms that the MIT licence does not cover.

Editorial conclusion

Adopt CodeNomad if you already run the OpenCode CLI for long sessions and want several instances, worktrees and remote browser access under one MIT-licensed roof; skip it if you need a stable release line, because every published version is a dev build from the dev branch. Before anything else, confirm OpenCode is installed and on your PATH, since the app proxies to it rather than shipping a model, and read packages/server/README.md for the TLS, auth and remote-access flags the top-level README only gestures at.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. NeuralNomadsAI/CodeNomad on GitHub
4. README
5. Releases