AI工作流

Requirements

• tmux (brew install tmux / apt install tmux)
• Tailscale (recommended) or any network path to your machine

Dependency Risk Scanner

Use the built-in scanner to report security and maintenance risk for direct dependencies:

bun run deps:risk

Machine-readable output:

bun run deps:risk:json

Policy:

• Security risk comes from bun audit --json findings and is aggregated by severity (low, moderate, high, critical).
• Maintenance risk comes from bun outdated and classifies version lag as major, minor, or patch behind latest.
• Local default threshold is high (high + critical fail).
• CI enforces security threshold breaches at critical only (bun run deps:risk:ci) while existing upstream high advisories are tracked; maintenance findings are warnings for prioritization.

You can override the security threshold with --threshold (or DEPENDENCY_RISK_FAIL_ON):

bun run deps:risk -- --threshold moderate

Install

Environment

PORT=4040
HOSTNAME=127.0.0.1
TMUX_SESSION=agentboard
REFRESH_INTERVAL_MS=5000
DISCOVER_PREFIXES=work,external
PRUNE_WS_SESSIONS=true
AGENTBOARD_PREFER_WINDOW_NAME=false
TERMINAL_MODE=pty
TERMINAL_MONITOR_TARGETS=true
VITE_ALLOWED_HOSTS=nuc,myserver
AGENTBOARD_DB_PATH=~/.agentboard/agentboard.db
AGENTBOARD_INACTIVE_MAX_AGE_HOURS=24
AGENTBOARD_EXCLUDE_PROJECTS=<empty>,/workspace
AGENTBOARD_HOST=blade
AGENTBOARD_REMOTE_HOSTS=mba,carbon,worm
AGENTBOARD_REMOTE_POLL_MS=2000
AGENTBOARD_REMOTE_TIMEOUT_MS=4000
AGENTBOARD_REMOTE_STALE_MS=45000
AGENTBOARD_REMOTE_SSH_OPTS=-o BatchMode=yes -o ConnectTimeout=3
AGENTBOARD_REMOTE_ALLOW_ATTACH=false
AGENTBOARD_REMOTE_ALLOW_CONTROL=false
AGENTBOARD_LOG_WATCH_MODE=watch

HOSTNAME controls which interfaces the server binds to (default 127.0.0.1 for localhost-only). With the default localhost binding, if Tailscale is detected the server also binds to your Tailscale IP automatically. Set to 0.0.0.0 to listen on all interfaces.

Security note: Agentboard has no built-in authentication. Anyone who can reach the server has full access to your terminal sessions, including the ability to run commands as your user. The default localhost binding is safe. Tailscale provides network-level auth for remote access. Avoid setting HOSTNAME=0.0.0.0 on untrusted networks (public WiFi, shared LANs) without an additional access control layer.

DISCOVER_PREFIXES lets you discover and control windows from other tmux sessions. If unset, all sessions except the managed one are discovered.

PRUNE_WS_SESSIONS removes orphaned agentboard-ws-* tmux sessions on startup (set to false to disable).

AGENTBOARD_PREFER_WINDOW_NAME (default false) controls how externally-discovered sessions are labeled. When false, the tmux session name is used (more meaningful than auto-renamed window names that follow the running process under tmux automatic-rename on). Set to true to use the tmux window name when it is non-empty and distinct from the session name — useful when you keep one shared session (e.g. dev) with one explicitly-named window per project (myapp, infra, ...).

TERMINAL_MODE selects terminal I/O strategy: pty (default, grouped session) or pipe-pane (PTY-less, works in daemon/systemd/docker without -t).

TERMINAL_MONITOR_TARGETS (pipe-pane only) polls tmux to detect closed targets (set to false to disable).

VITE_ALLOWED_HOSTS allows access to the Vite dev server from other hostnames. Useful with Tailscale MagicDNS - add your machine name (e.g., nuc) to access the dev server at http://nuc:5173 from other devices on your tailnet.

All persistent data is stored in ~/.agentboard/: session database (agentboard.db) and logs (agentboard.log). Override paths with AGENTBOARD_DB_PATH and LOG_FILE.

AGENTBOARD_INACTIVE_MAX_AGE_HOURS limits History sessions shown in the UI to those with recent activity (default: 24 hours). Older sessions remain in the database but are not displayed or processed for orphan rematch. The env var name is kept for compatibility.

AGENTBOARD_EXCLUDE_PROJECTS filters out sessions from specific project directories (comma-separated). Use <empty> to exclude sessions with no project path. Useful for hiding automated/spam sessions.

AGENTBOARD_SKIP_MATCHING_PATTERNS controls which orphan sessions skip expensive window matching (comma-separated). Defaults: <codex-exec> (headless Codex exec sessions), /private/tmp/*, /private/var/folders/*, /var/folders/*, /tmp/*. Patterns support trailing * for prefix matching. Set to empty string to disable skip matching entirely.

AGENTBOARD_HOST sets the host label for local sessions (default: hostname).

AGENTBOARD_REMOTE_HOSTS enables remote tmux polling over SSH. Provide a comma-separated list of hosts (e.g., mba,carbon,worm). Remote sessions show live status (working/waiting/permission) via pane content capture over SSH.

AGENTBOARD_REMOTE_POLL_MS, AGENTBOARD_REMOTE_TIMEOUT_MS, and AGENTBOARD_REMOTE_STALE_MS control remote poll cadence, SSH timeout, and stale host cutoff.

AGENTBOARD_REMOTE_SSH_OPTS appends extra SSH options (space-separated).

AGENTBOARD_REMOTE_ALLOW_ATTACH enables interactive terminal attach to remote sessions (input, resize, copy-mode). When false (default), remote sessions are view-only.

AGENTBOARD_REMOTE_ALLOW_CONTROL enables destructive remote session management (create, kill, rename) via the UI. Setting this to true implies REMOTE_ALLOW_ATTACH=true. Kill and rename are restricted to agentboard-managed sessions — externally-discovered remote sessions cannot be killed or renamed even with control enabled.

AGENTBOARD_LOG_WATCH_MODE selects the log detection strategy: watch (default) uses fs.watch for instant file-change detection, poll falls back to periodic directory scanning. Use poll if you experience issues with filesystem notifications (e.g., on network-mounted home directories). On Linux, watch mode automatically includes a 15-second fallback poll since fs.watch({ recursive: true }) has known platform bugs.

SSH multiplexing (recommended): Each poll cycle opens SSH connections to every remote host. Enable SSH connection multiplexing to reuse connections and reduce overhead from ~200-500ms to ~5ms per poll. Add to your ~/.ssh/config:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

Then create the sockets directory: mkdir -p ~/.ssh/sockets && chmod 700 ~/.ssh/sockets

Troubleshooting