Getting started

Use Node 26.4.0 with fnm. The setup wizard can configure KiloCode, OpenAI, or Anthropic as the Flue model provider.

Install from npm

Neondeck currently publishes beta releases on npm's next channel. The package and installed CLI are both named neondeck.

fnm install 26.4.0
fnm use 26.4.0
npm install --global neondeck@next

Run the CLI wizard

Start with the guided terminal setup. It prepares runtime state, writes local secrets to the runtime home, configures the agent model, adds repositories, applies a dashboard preset, and can create initial schedules. When KiloCode is selected, init can discover and search available KiloCode models before writing model config.

neondeck init

The same CLI is the base for direct command-and-control workflows and the future OpenTUI client.

neondeck status
neondeck repo add ~/dev/neondeck
neondeck watch-pr pandemicsyn/neondeck#123
neondeck tui

Initialize runtime home

The app creates a runtime home on first start. You can also prepare it explicitly before launching the dashboard. For new installs, use neondeck init. Any command that reads app state also creates missing runtime-home files without rerunning the wizard.

neondeck status

By default this writes to ~/.config/neondeck. Set NEONDECK_HOME when you want an isolated test home.

neondeck --home .neondeck-test status

Configure secrets

Packaged and local app secrets live in runtime-home .env, for example ~/.config/neondeck/.env. For checkout-based development, repo-root .env is also supported as a dev-only fallback.

KILOCODE_API_KEY=...
KILOCODE_ORGANIZATION_ID=...
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GITHUB_TOKEN=...
GITHUB_LOGIN=...

Provider credentials

Flue model strings use provider-qualified names such as kilocode/kilo-auto/balanced, openai/gpt-5.5, or anthropic/claude-sonnet-4-6. Hosted providers use their normal API credentials or a platform binding. A ChatGPT or Codex subscription login is not a documented Flue provider credential path.

Neondeck allowlists KiloCode, OpenAI, and Anthropic provider configuration in runtime config.json. Provider settings store environment variable names, not raw secrets or arbitrary base URLs. Provider registration changes require a server restart. See configuration for the full runtime file model.

Run the local dashboard

neondeck service install
neondeck open

The service command installs and starts Neondeck for your login. The open command waits for a healthy local server, then opens the dashboard on a companion display, a vertical panel, or your primary monitor.

Open a specific window profile

Named profiles can set size, placement, and kiosk behavior for a particular display.

neondeck open sidebar
neondeck open xeneon --kiosk

neondeck service install writes a macOS launchd agent or Linux systemd user unit with absolute Node and Neondeck CLI entry paths. Re-run it after changing Node versions. neondeck open probes /api/health, starts the installed service when present, or starts a detached serve process when no service exists, then opens the dashboard.

For a persistent sidebar window, install the dashboard as a browser app from the dashboard docs. PWA windows remember their own bounds; neondeck open sidebar is a launch-time placement tool for Chromium app-mode windows.

Run Neon commands

Commands can be typed into the chat panel or invoked through the command-run Flue workflow. Deterministic command results are stored as workflow summaries for follow-up agent context. In chat, /briefing is conversational: it dispatches a normal turn to the active display-assistant session.

curl -X POST 'http://127.0.0.1:3583/api/briefings/run' \
  -H 'content-type: application/json' \
  -d '{"profileId":"morning","trigger":"dashboard"}'

Current commands:

/repo-status [repo-id]
/review-queue
/review-pr <repo#number|owner/repo#number|url>
/fix-ci [repo#number|owner/repo#number]
/explain-ci [--report] [repo#number|owner/repo#number]
/summarize-pr [repo#number|owner/repo#number]
/draft-pr-description [repo-id|owner/repo]
/prepare-pr [repo-id|owner/repo]
/review-local [repo-id|owner/repo]
/briefing
/reasoning [off|minimal|low|medium|high|xhigh]
/memory ...
/dev-doctor
/watch-pr <repo#number|owner/repo#number|url>

Configure repositories

Repositories live in runtime-home repos.json. Neon should mutate config through typed actions rather than direct file edits. The repo registry powers GitHub PR queues, watches, release checks, local repo status, and dev doctor diagnostics. See the CLI reference for repo and watch commands.

Runtime skills

The built-in Neondeck runtime skill is an application-owned Flue skill. User runtime skills load from skills/ inside the runtime home, plus configured external skill roots, and are registered as Flue skills when the agent initializes. Start a new session or restart the server after changing runtime skills. Treat runtime skill directories as trusted input and do not place secrets in skill resources. See agent runtime for how skills fit with actions and workflows.

Agent models

Configure the display assistant, utility, and subagent model choices in runtime-home config.json. Environment variables remain fallback values, but runtime config is the preferred local control point.

{
  "version": 1,
  "models": {
    "displayAssistant": "kilocode/kilo-auto/balanced",
    "displayAssistantThinkingLevel": "medium",
    "utility": "kilocode/kilo-auto/fast",
    "utilityThinkingLevel": "low",
    "subagents": {
      "default": "kilocode/kilo-auto/balanced",
      "defaultThinkingLevel": "medium",
      "repoResearcher": "kilocode/kilo-auto/balanced",
      "repoResearcherThinkingLevel": "medium",
      "ciInvestigator": "kilocode/kilo-auto/balanced",
      "ciInvestigatorThinkingLevel": "medium",
      "releaseReviewer": "kilocode/kilo-auto/balanced",
      "releaseReviewerThinkingLevel": "medium"
    }
  }
}

The chat agent can update these fields through the typed neondeck_config_update_agent_models action. Model strings must reference allowlisted providers. Thinking levels use Flue's thinkingLevel values such as low, medium, and high. The utility model is optional; when skipped, Neondeck falls back to the display assistant and recommends a cheaper model for bounded helper work.

Execution approvals

Neondeck keeps host execution action-mediated. The default execution backend is local; exe.dev runs through the Flue sandbox adapter against an existing VM.

{
  "version": 1,
  "execution": {
    "defaultBackend": "local",
    "enabledBackends": ["local"],
    "approvalMode": "manual",
    "unattended": "deny",
    "exeDev": {
      "lifecycle": "existing-vm",
      "vmHostEnv": "EXE_VM_HOST",
      "sshKeyEnv": "EXE_SSH_KEY",
      "apiTokenEnv": "EXE_API_TOKEN"
    },
    "preapprovedCommands": [
      {
        "id": "test",
        "command": "npm test",
        "match": "exact",
        "backends": ["local"],
        "description": "Run the repo test suite."
      }
    ]
  }
}

Preapproved commands must be single commands without shell operators, redirection, subshells, or newlines. Commands that do not match the preapproval list require interactive approval and are denied in unattended contexts. Hardline destructive commands cannot be preapproved.

Use neondeck_execution_policy_lookup to inspect the active policy, neondeck_execution_policy_check to classify a proposed command without running it, and neondeck_config_update_execution_policy to update config. Use neondeck_execution_request_approval and neondeck_execution_run for the model-callable approval/run path. Approval resolution is dashboard/API/user-owned, not model-callable. Policy updates are audited in config_history; executions are audited in execution_approvals.

Trusted-local execution runs on your machine and is best for local git or developer commands you already trust. exe.dev is the isolated sandbox option; enable it explicitly by adding "exe.dev" to enabledBackends after EXE_VM_HOST points at an existing VM and SSH auth is configured.

Repo-scoped exe.dev work should first call neondeck_exedev_checkout_sync for a configured repoId or managed worktreeId. Subsequent neondeck_execution_run calls can pass the same target so the remote cwd and explicitly enabled env forwarding apply. Env audit metadata records source ids and keys, not values, and Neondeck does not filter env vars by heuristic name.

Verify locally

npm run check
npm run test:integration
npm run verify

npm run check is the fast loop with unit tests. npm run test:integration runs the slower integration suites for command paths, worktrees, Kilo, and other host-backed flows. npm run verify runs lint, typecheck, all tests, formatting, the dashboard build, the Flue Node build, and the Astro docs site build.

Run the docs site

npm run docs:astro-dev

The Astro marketing/docs site runs separately from the local dashboard and deploys to Cloudflare.

Deploy neondeck.dev

npm run docs:deploy

The Worker is configured in docs/wrangler.jsonc with custom domains for neondeck.dev and www.neondeck.dev. See deployment for the deploy surface.