Viewport Daemon

Runtime supervision and orchestration layer for AI coding agents.

What it does

1. Launches and manages agent sessions.
2. Tracks lifecycle, permissions, and session state.
3. Exposes local HTTP and WebSocket APIs for control and monitoring.
4. Supports discovery and resume flows for existing sessions.

Requirements

1. Node.js 20+
2. npm 10+

One Command Install

curl -fsSL https://raw.githubusercontent.com/viewportai/daemon/main/scripts/install.sh | bash

This installs @viewportai/daemon globally, then runs vpd setup.

Local development install (from this repo, no npm publish needed):

./scripts/install-dev.sh --yes --no-service --no-prereqs --no-hooks

Local development link mode:

./scripts/install-dev.sh --link --yes --no-service --no-prereqs --no-hooks

Local uninstall/reinstall:

npm run dev:uninstall       # removes global package + launchd/systemd user service
npm run dev:uninstall:all   # also removes daemon home/state
npm run dev:reinstall

Quick start

npm ci
npm run build
npm run test
npm run check

Flag-driven test entry (single command surface):

npm run test                  # unit suite (default)
npm run test --verify        # setup/service-focused verification suite
npm run test --e2e           # protocol e2e suite
npm run test --fullstack     # localhost fullstack CLI e2e
npm run test --env           # local environment verification
npm run test --service       # local environment + service verification

First-run onboarding:

vpd setup

Non-interactive recommended defaults:

vpd setup --yes

Custom choices:

vpd setup --choose

CLI

npm run build
node dist/index.js --help

Boot service setup (user-level):

vpd service install
vpd service status

Linux VPS note: For user-level systemd service auto-start after reboot, enable linger once:

sudo loginctl enable-linger "$USER"

Quality gates

npm run typecheck
npm run lint
npm run format:check
npm run test
npm run check

Testing Setup Flow

# fast setup-related tests
npm run test:setup

# full repository quality gate
npm run check

# manual verification test (no service or package installs)
VIEWPORT_HOME="$(mktemp -d)" vpd setup --yes --no-service --no-prereqs --no-hooks

# full local environment verification (isolated home + dedicated listen target)
npm run verify:env

# include OS service checks (launchd/systemd)
npm run verify:env:service

# package/install verification from local tarball in isolated prefix
npm run verify:install

# one-command verification gate
npm run verify:repo

# CI-aligned Linux verification path
npm run verify:linux:ci

Repository standards

1. Semantic commits (feat:, fix:, refactor:, test:, docs:, chore:).
2. One logical change per commit.
3. Changes to protocol or runtime behavior require matching tests.

Release

This package publishes as @viewportai/daemon.

1. Merge semantic commits to main.
2. CI must pass.
3. Release workflow computes version (feat => minor, fix => patch, BREAKING CHANGE => major), tags, and publishes to npm using NPM_TOKEN.

See docs/releasing.md for setup and operations. See docs/testing.md and docs/developer-workflows.md for local validation workflows.