Getting started

Install Neondeck, run the guided setup, and open the local dashboard. You need Node.js 26 or newer and credentials for at least one supported model provider.

1. Install Node.js

Install Node.js 26 or newer using any installer or version manager, then confirm the active version: 

node --version

2. Install Neondeck

Neondeck currently publishes beta releases on npm's next channel. 

npm install --global neondeck@next

3. Run the setup wizard

neondeck init

The wizard creates your local runtime home and walks you through the essential setup:

  • Configure a model provider.
  • Check the Git identity used for Autopilot commits.
  • Optionally add repositories, choose a dashboard preset, and create initial schedules.

Choose a model provider

Neondeck supports KiloCode, OpenAI, Anthropic, OpenRouter, OpenCode Zen, Google Vertex AI Gemini, a ChatGPT subscription, and custom OpenAI-compatible endpoints.

KiloCode, OpenRouter, OpenCode, and Vertex offer searchable model catalogs during setup:

  • Vertex uses Pi's bundled Gemini catalog. Authenticate with a Google Cloud API key or Application Default Credentials, plus a project and location.
  • OpenRouter uses your account-filtered catalog when the API key permits it, then falls back to the public catalog. Eligible new models may appear before Pi's bundled metadata catches up.
  • Search results are ranked by relevance and, when available, provider recency. Use More results to browse every match, start another search, or return to the model choices.

Confirm your Git identity

Autopilot commits need an explicit Git identity. If global user.name or user.email is missing, the wizard offers to configure both values and user.useConfigOnly so Git cannot silently invent an identity from the machine account.

Complete author and committer overrides in the runtime-home .env are also accepted. Temporary shell exports do not suppress the warning.

By default, local state is stored in ~/.config/neondeck. See Configuration for runtime-home, credentials, provider, and model details.

GitHub token for pull request workflows

Neondeck reads GITHUB_TOKEN from the runtime-home .env; it does not reuse the credential shown by gh auth status. For complete private-repository PR review and CI context, use a classic personal access token with the repo scope. If your organization uses SAML SSO, authorize the token for that organization, and confirm that the organization permits classic PAT access.

4. Start Neondeck

Start Neondeck and open the dashboard:

neondeck open

When no login service is installed, the server stays attached to this terminal. Press Ctrl-C to stop it.

On macOS and Linux, you can instead install a managed background login service: 

neondeck service install
neondeck open

Use neondeck serve when you want the foreground server without opening a browser.

5. Check the installation

neondeck status

Once the dashboard is running, use the CLI reference to add repositories, configure watches, inspect authentication, and run diagnostics.

When a newer release is available, Neondeck links to the upgrade guide from its dashboard banner.

Optional: open Neondeck on a secondary display

Neondeck works in a normal browser window. You do not need a secondary display, a fixed-size window, or a Chromium-family browser.

If you want a dedicated companion-display window with a fixed size or position, new runtime homes include named sidebar and xeneon window profiles: 

neondeck open sidebar --browser "/path/to/chromium"
neondeck open xeneon --browser "/path/to/chromium"

Running open again opens another dashboard without changing the already-running server. Neondeck normally uses the OS default browser; pass a Chromium-family executable with --browser <path> to apply a profile's size, position, or kiosk settings.

Profile names and window settings come from dashboard.json. See the Dashboard guide for browser app installation, display layouts, and window behavior.

Development

Working from a source checkout? See the development guide on GitHub for repository setup, npm scripts, tests, builds, packaging, and docs development.