Execution environments

Neon separates its brain from its workspace. The brain — config, app state, GitHub facts, sessions, schedules — always runs on the host inside the Neondeck server. The workspace — checkouts, file edits, and shell commands — is governed: the model never holds a raw shell, and every command runs through a policy gate you can inspect and audit.

flowchart TB subgraph Brain["Host: Neon's brain"] Agent["display assistant (virtual Flue sandbox)"] Actions["typed actions and tools"] Policy["execution policy allow / ask / deny"] Approvals["approvals + audit"] State["config + SQLite + GitHub API"] end subgraph Work["Workspaces"] LocalExec["local backend host shell"] ExeDev["exe.dev backend VM over SSH"] Repos["declared repos + managed worktrees"] end Agent --> Actions Actions --> Policy Policy --> Approvals Approvals --> LocalExec Approvals --> ExeDev Actions --> Repos Actions --> State

Flue sandbox patterns, and which ones Neondeck uses

Flue offers three sandbox patterns for an agent's built-in file and shell tools. Neondeck takes a deliberate position on each:

Virtual (used, the default). Neon's chat agent works in Flue's in-memory /workspace. It is scratch space only — no host files, nothing persists.
Local (deliberately unused). Flue's local() sandbox would give the model direct host filesystem and shell access, bypassing every Neondeck policy gate. No Neondeck agent uses it, and none should.
Remote Flue sandbox (planned). Neondeck already supports policy-mediated command and repo execution on an existing exe.dev VM. The later workspace mode would also relocate the agent's built-in Flue sandbox and the entire managed workspace to that VM. See below.

Instead of a shell, the agent gets mediated access to everything through typed actions: repo files through repo-edit, commands through execution actions, isolated changes through managed worktrees, config through config actions. Access is broad; it is never direct.

The execution policy gate

Every host or VM command flows through neondeck_execution_run and is checked against the config-backed execution policy first:

allow: the command matches a preapproved entry in execution.preapprovedCommands and runs immediately. Preapproved commands are single commands without shell operators; hardline destructive commands cannot be preapproved.
ask: anything else needs an approval, resolved by you in the dashboard, API, or CLI — never by the model. Unattended contexts (scheduler, autopilot) deny instead of asking.
deny: refused with a typed reason.

Every run — allowed, approved, or failed — records an approval row with exit code, output previews, and backend metadata, visible in the Runtime Overview panel.

Backends

execution.defaultBackend and execution.enabledBackends select where approved commands execute:

local: the host machine, in the server's environment.
exe.dev: an existing exe.dev VM you own, reached over SSH. Configure it with execution.exeDev (vmHostEnv, default EXE_VM_HOST; sshKeyEnv, default EXE_SSH_KEY; falls back to SSH_AUTH_SOCK). Neondeck adapts the VM through Flue's exe.dev sandbox adapter but never creates or deletes VMs on your behalf.

Repo-scoped exe.dev work uses neondeck_exedev_checkout_sync to clone or sync a declared repo (or a managed worktree) onto the VM under execution.exeDev.remoteRoot, with every git step running through the same policy gate. Environment forwarding to the VM is opt-in per scope (execution.exeDev.env), sourced from repo env files, config vars, or named host variables, and each forwarded source is recorded in the execution audit.

Repo boundaries and worktrees

File reads and edits use the repo-edit actions, which operate only inside declared Neondeck repo workspaces: path containment, symlink escape checks, and sensitive-path rules return typed policy errors instead of prompting. Autonomous change flows (autopilot, Kilo results) never mutate your primary checkout — they work in managed worktrees. The minimal watched-PR Autopilot keeps its review artifact as an ordinary local commit; explicit fixer and Kilo workflows may still use prepared-diff records and their separate review gates.

Authority follows task origin. In a human-driven chat, typed repo actions may edit, commit, and push to the linked PR head without creating routine execution approvals. A shared guardrails config block still denies forbidden paths and destinations, and asks once before high-risk or over-limit pushes. That acknowledgment is bound to the reviewed commit and effect, so a changed worktree prompts again. The current Autopilot owner loop gives each watcher or direct-human turn only the bounded tools allowed by its current mode. Automatic delivery additionally reruns every configured targeted check, refetches complete GitHub facts, proves the current PR head, policy, permissions, and push identity, and uses a non-force expected-head push. Any uncertainty blocks with the local commit retained for review.

Planned: exe.dev workspace mode

Status: planned, not yet implemented. A single config switch will relocate the entire workspace to your exe.dev VM:

{
  "workspace": { "mode": "exe.dev" }
}

With the mode on, repo checkouts, managed worktrees, repo-edit file operations, verification commands, and the agent's own Flue sandbox all live on the VM; GitHub facts, config, sessions, and schedules stay on the host. The trust model is unchanged — the policy gate controls what runs, not where — and there is no silent fallback: if the VM is unreachable, workspace operations fail with typed errors and runtime status says why. The design is documented in the workspace mode plan.

See Security for secrets, tokens, and local API trust boundaries, and Agent runtime for how actions and workflows fit together.