Skip to content

Latest commit

 

History

History
71 lines (46 loc) · 5.24 KB

install.md

File metadata and controls

71 lines (46 loc) · 5.24 KB

Install CodeNomad

Choose a local desktop host or run the standalone server. In both cases, OpenCode owns the shared native service and history.

Desktop downloads {#desktop-downloads}

  1. Open the download page.
  2. Choose the build matching your operating system and processor.
  3. Extract the ZIP or install/run the platform package, then launch CodeNomad.
Platform Electron release Tauri release Platform notes
macOS ZIP, Intel or Apple Silicon ZIP, Intel or Apple Silicon Tauri: macOS 14+; Electron: macOS 13.5+.
Windows ZIP, x64 Installer, x64 Windows 10 or later; Tauri uses WebView2.
Linux Debian package, x64 AppImage, x64 Built and tested on Ubuntu 24.04; compatibility with older distributions is not guaranteed.

Desktop releases include the runtime resources needed by the backend and OpenCode installer, so you do not need a separate Node.js/npm installation to use them. Git is not bundled. Native agent browser automation is supported in Electron and Tauri on Windows, macOS and Linux. Tauri macOS/Linux use WebKit previews and native mobile profiles with engine-specific density and input limits; see browser previews.

For a verified download blocked at launch, see platform troubleshooting. Never run an untrusted archive merely to bypass a warning.

Install on Linux {#linux-install}

From the folder containing your downloaded release, substitute its actual version and filename:

sudo apt install ./CodeNomad-Electron-linux-x64-<version>.deb

For the Tauri AppImage:

chmod +x CodeNomad-Tauri-linux-x64-<version>.AppImage
./CodeNomad-Tauri-linux-x64-<version>.AppImage

If FUSE is unavailable, use the AppImage's extraction-and-run mode:

./CodeNomad-Tauri-linux-x64-<version>.AppImage --appimage-extract-and-run

The Electron Debian installation configures Chromium's sandbox. Do not disable the sandbox as an installation workaround. Linux Tauri graphics issues have a targeted WebKit workaround.

Requirements {#requirements}

Requirement Where it must be available Current requirement
OpenCode CLI Selected execution host, including the selected WSL distribution where applicable Minimum 2.3.0; 2.3.0 is the recommended/qualified target. Newer or custom versions undergo contract validation rather than an untested-version ban.
Git CodeNomad backend account's PATH Required for repository identity, Git operations and worktrees.
Node.js/npm Standalone-server and source-build host Node.js 24 LTS; reproducible source builds use the version pinned in .node-version. Desktop releases include their own: Electron's integrated Node or Tauri's bundled Node, with npm.
Workspace folder Backend-accessible disk An explicitly opened physical folder, not a device-local folder inferred by a remote browser.

On Windows, install Git for Windows with command-line/third-party access enabled. A user-writable, per-user installation is sufficient. On macOS/Linux, use Git's platform instructions.

After changing PATH, fully quit and relaunch the desktop app, or restart the standalone backend under the intended account. Reloading a browser does not update the backend environment. Git available only inside WSL does not satisfy a Windows backend's Git requirement.

Without Git, you can still open a physical folder and use directory-only conversations, including asking the agent for installation help. Repository/worktree operations remain unavailable; session access stays limited to that exact folder. The agent's execution host can differ from the backend host, so install Git for the backend, not only for the agent's shell.

Select OpenCode on first launch {#first-launch}

  1. In setup, choose a compatible existing executable or use the offered OpenCode installation action.
  2. Verify the runtime status before opening a project.
  3. Revisit Preferences → OpenCode to manage the executable, installation and shared service separately.

CodeNomad prefers compatible executables on PATH and supports an explicitly selected executable. If PATH starts an older OpenCode, setup offers to replace an npm-installed OpenCode 1.x after confirmation, or to install OpenCode 2 for CodeNomad beside an installation made another way, which it never modifies; see OpenCode setup. Installing/updating a CLI does not silently restart an already running shared service. See OpenCode setup for restart/reload consequences, WSL and session environment.

Use a browser instead {#browser-install}

Install Node.js/npm, Git and OpenCode on the server host, then use the server launch procedures. Connect with the printed address, configured authentication and a trusted certificate. A browser/PWA needs a live backend; it is not an offline copy of your projects.

For ports, bindings and TLS, use direct access. To pair a device without opening inbound ports, use Remote Control. For development and packaging commands, see source builds.