Panorama Gateway

Gateway service for connecting host-side runtime capabilities to Panorama.

In local mode, a team can pair multiple gateways from different machines; each gateway instance is identified by its own gateway_id.

VM guest mode starts the same gateway inside a provisioned VM with scoped drive-sync credentials so the guest can mirror Panorama drive resources.

Usage

Pair this gateway instance with a team using a pairing code:

panorama-gateway pair <PAIRING_CODE>

For local package development:

PANORAMA_ENV=dev pnpm --filter @panorama-ai/gateway dev -- pair <PAIRING_CODE>

Or pass backend overrides directly:

SUPABASE_URL="https://your-project.supabase.co" \
SUPABASE_ANON_KEY="your-anon-key" \
pnpm --filter @panorama-ai/gateway dev -- pair <PAIRING_CODE>

Start this gateway and begin listening for jobs (foreground in dev, background for built CLI):

pnpm --filter @panorama-ai/gateway dev -- start

Force this gateway into the background (built binary only):

pnpm --filter @panorama-ai/gateway build
pnpm --filter @panorama-ai/gateway start -- --daemon

Run in the foreground (built binary):

pnpm --filter @panorama-ai/gateway start -- --foreground

Stop this gateway:

pnpm --filter @panorama-ai/gateway dev -- stop

Check this gateway's status:

pnpm --filter @panorama-ai/gateway dev -- status

Manage host machine control on this host (the CLI command is still full-control for compatibility):

pnpm --filter @panorama-ai/gateway dev -- full-control status
pnpm --filter @panorama-ai/gateway dev -- full-control enable
pnpm --filter @panorama-ai/gateway dev -- full-control disable

Tail logs:

pnpm --filter @panorama-ai/gateway dev -- logs --lines 200

Optional flags:

• --device-name "My MacBook"
• --verbose, -v (show technical details like paths, IDs, and PIDs)
• --env local|dev|test|stage|prod
• --env-file /path/to/.env
• --mode local|managed (start only; default local)
• --foreground (run in the foreground)
• --daemon (force background for built CLI)
• --config-dir /path/to/dir
• --config-path /path/to/gateway.json
• --log-path /path/to/gateway.log
• --pid-path /path/to/gateway.pid
• --claude-cli /path/to/claude
• --codex-cli /path/to/codex
• --gemini-cli /path/to/gemini
• --no-follow (show logs without follow)

The gateway stores credentials in ~/.panorama/gateway/gateway.json by default. Override with --config-path or PANORAMA_GATEWAY_CONFIG_PATH.

Environment

The published CLI ships with embedded production backend defaults, so end users can run pair without setting Supabase values.

For development or backend overrides, the gateway reads these values (CLI flags override environment variables):

• SUPABASE_URL (or PANORAMA_SUPABASE_URL)
• SUPABASE_ANON_KEY (or PANORAMA_SUPABASE_ANON_KEY / SUPABASE_PUBLISHABLE_KEY)

When --env or PANORAMA_ENV is provided, the gateway loads .env.<env> from the repo root (falls back to .env for local). You can always point to a specific env file with --env-file.

The gateway runs CLI providers using the current user environment (HOME, PATH, etc.) so it matches what you see when running the CLIs directly.

Foreground gateway mode is also used inside managed VM guests. VM guest bootstrap persists vmGuest identity in the gateway config and passes the backend credentials needed by the gateway:

• PANORAMA_SUPABASE_URL
• PANORAMA_SUPABASE_ANON_KEY
• PANORAMA_VM_BOOTSTRAP_TOKEN
• PANORAMA_VM_BOOTSTRAP_FORCE (optional)
• PANORAMA_VM_DEVICE_NAME (optional)

When the worker has VM_DRIVE_SYNC_ENABLED enabled, the VM guest receives PANORAMA_DRIVE_SYNC_ENABLED=1 plus these low-level sync settings:

• PANORAMA_DRIVE_SYNC_ENABLED (optional, default false)
• PANORAMA_DRIVE_SYNC_ROOT (optional, default /panorama/drives)
• PANORAMA_DRIVE_SYNC_STATE_DIR (optional, default /var/lib/panorama/drive-sync)
• PANORAMA_DRIVE_SYNC_CLIENT_KEY (optional; default is derived from VM identity and local sync state; managed VM guest provisioning does not forward this override)
• PANORAMA_DRIVE_SYNC_CHANGE_LIMIT (optional, default 50)
• PANORAMA_DRIVE_SYNC_MAX_BATCHES_PER_TICK (optional, default 25)
• PANORAMA_DRIVE_SYNC_DEBOUNCE_MS (optional, default 1000)
• PANORAMA_DRIVE_SYNC_POLL_INTERVAL_MS (optional, default 5000)
• PANORAMA_DRIVE_SYNC_LOCAL_AUDIT_INTERVAL_MS (optional, default 300000)
• PANORAMA_DRIVE_SYNC_NETWORK_TIMEOUT_MS (optional, default 60000) The foreground gateway starts a non-fatal drive sync supervisor scoped to that VM. If sync startup fails, the gateway still accepts normal VM remote-shell jobs.

Runtime Structure

The gateway package is published to NPM as a single CLI, with separate boundaries for local host orchestration and VM guest drive sync.

Local runtime modules:

• src/gateway-local-runtime.ts owns local startup orchestration: paired session loading, provider validation, job controller wiring, signal handling, and lifecycle coordination.
• src/local-runtime/drive-sync-supervisor.ts owns optional VM guest drive sync startup/shutdown for foreground gateways that have vmGuest identity.
• src/local-runtime/heartbeat-supervisor.ts owns local capability refreshes and heartbeat reporting.
• src/local-runtime/restart-supervisor.ts owns package/probe watching and drain-before-restart behavior.
• src/local-runtime/shutdown-supervisor.ts owns drain, termination, offline heartbeat, and residual job cleanup behavior.

VM guest drive-sync modules:

• src/drive-sync/config.ts resolves the VM guest drive-sync environment contract.
• src/drive-sync/drive-sync.ts owns the sync loop that reconciles local files with Panorama drive entries.
• src/drive-sync/drive-sync-planner.ts, src/drive-sync/drive-sync-remote-planner.ts, and src/drive-sync/drive-sync-state-applier.ts own sync planning and local state application.
• src/drive-sync/drive-sync-filesystem.ts and src/drive-sync/drive-sync-transfer.ts own filesystem scans and direct file transfer helpers.
• src/drive-sync/drive-sync-scheduler.ts owns periodic sync execution.

Shared runtime helpers:

• src/process-output-capture.ts owns bounded stdout/stderr capture for shell execution and provider streaming.
• src/provider-runtime-utils.ts owns provider environment construction and command/result parsing helpers used by CLI provider adapters.
• src/subagent-adapters/output-format.ts owns shared subagent output format normalization.

Local mode is driven by a paired gateway session and user-delegated host capabilities. VM guest drive sync is scoped by VM identity and only mirrors Panorama drive resources for that VM.

Execution Bridge and Trust Model

The gateway has two primary host surfaces:

• Local gateways connect Panorama's control plane to a machine/account the team controls.
• VM guest drive sync runs inside a provisioned VM and mirrors Panorama drive resources through scoped VM credentials.

Local mode:

• Gateway processes run as the logged-in user and are designed to behave like direct local CLI usage.
• Gateway hosts are a user-delegated host trust zone. Treat gateway access as equivalent to local CLI access for that user account.
• Provider child processes inherit user environment semantics, but gateway-internal secrets are scrubbed before launch.
• Provider-side execution controls rely on built-in provider flags (for example Codex read-only sandbox + tool flags), not heavyweight host isolation.
• Machine-control capabilities are layered:
  • host machine-control toggle (panorama-gateway full-control enable)
  • team-level gateway machine-control toggle (Team Integrations UI / set-gateway-full-control)
  • resource-level opt-in (config.full_control=true for gateway subagents, metadata.full_control=true for remote_shell resources)
• Gateway state is stored locally under ~/.panorama/gateway by default and includes pairing/session tokens needed for reconnects.
• On POSIX platforms, gateway state directories/files are enforced as owner-only (0700 for dirs, 0600 for files).

VM guest drive sync:

• Guest gateway processes run with scoped VM identity.
• Drive sync uses only the VM drive-sync token and linked VM metadata.
• VM guest drive sync does not use paired-user gateway session material.

Recommended deployment model:

• Use a machine/account you control (for example a dedicated cloud VM user) for each gateway instance.
• A team can pair multiple gateways (e.g. different developer machines, CI hosts, or VMs). Each gateway gets its own gateway_id and reports status independently.
• Treat gateway host access as equivalent to local CLI access for that user account.
• For Panorama-managed VM guest images, start from packages/gateway/vm-template/Dockerfile and keep the guest gateway bridge scoped to its linked VM identity.

If you hit a permission hardening error, fix ownership/permissions on the gateway state path and re-run pair or start.

Auto-Restart on Upgrade

Each gateway CLI instance watches its installed package version and restarts itself when the version changes. It drains in-flight jobs first and then respawns using the same CLI arguments.

Defaults:

• Poll interval: 30 seconds
• Auto-restart enabled for the built CLI (disabled for pnpm dev)

Environment overrides:

• PANORAMA_GATEWAY_AUTO_RESTART=0 to disable
• PANORAMA_GATEWAY_RESTART_CHECK_MS=30000
• PANORAMA_GATEWAY_RESTART_MAX_WAIT_MS to force a restart after a max wait (optional)

Job Handling

Gateway currently handles:

• diagnostic jobs for host/provider validation
• model_run jobs for provider model execution
• subagent_run and subagent_cancel jobs for delegated provider harnesses on gateway hosts
• shell_exec jobs for remote shell execution via remote shell resources

For JSON model runs, the worker prefers providers that support explicit output schema mode. JSON streaming support is optional and used as a compatibility path when schema mode is unavailable.

Existing capability names map to these product surfaces:

• model_execution means the gateway can run local Claude/Codex/Gemini model calls and gateway subagents. Gateway subagents default to restricted provider sandboxes unless config.full_control=true explicitly requests elevated provider mode.
• remote_shell means the gateway can receive shell_exec jobs through a remote_shell resource.
• machine_control means direct host-control authority is available for elevated gateway subagents and remote shell command execution.

Remote shell execution contract:

• shell_exec runs one foreground shell command through the host shell with -lc.
• Commands start from /; callers must include cd /path && ... when they want another working directory.
• The default timeout is 30 seconds and the maximum accepted timeout is 10 minutes.
• Stdout/stderr are returned inline with truncation flags. Remote shell exec does not create overflow artifacts.
• The gateway does not track background processes after the foreground command exits. Callers may start background work intentionally, but they must manage it with later shell commands.

CLI Provider Notes

See packages/gateway/CLI_PROVIDERS.md for current findings on Claude Code, Codex CLI, and Gemini CLI usage patterns.

Packaging and Smoke Checks

The gateway is expected to remain publishable to NPM. The package publishes only the built dist output and this README; source files are not part of the runtime package.

Run these checks before shipping gateway runtime changes:

pnpm --filter @panorama-ai/gateway test
pnpm --filter @panorama-ai/gateway build
pnpm --filter @panorama-ai/gateway verify:packaged-cli

Use targeted smoke tests when changing one runtime surface:

pnpm --filter @panorama-ai/gateway exec tsx --test test/gateway-start-command.test.ts test/gateway-local-runtime.test.ts test/local-runtime-heartbeat-supervisor.test.ts test/local-runtime-restart-supervisor.test.ts test/local-runtime-shutdown-supervisor.test.ts
pnpm --filter @panorama-ai/gateway exec tsx --test test/drive-sync.test.ts test/drive-sync-scheduler.test.ts

panorama-gateway start requires paired local gateway state. panorama-gateway start with VM guest drive sync requires scoped VM drive-sync credentials. Prefer the packaged CLI check plus targeted runtime tests for local development smoke validation unless you are intentionally testing against a live paired gateway or VM guest.