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 a scoped runtime identity. Drive files move through explicit Panorama CLI transfers.

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)

Managed guests also receive an initial per-VM egress credential. The gateway copies it into its owner-only config and starts a loopback relay; agent children receive only the relay URL, never the upstream bearer. Seven days before expiry, the authenticated heartbeat path stages a digest-only replacement, drains the gateway for restart, and acknowledges activation from the replacement process. No credential renewal travels through an agent-visible gateway job.

If the VM remains stopped or offline until that credential lacks the 15-minute boot safety window, it cannot self-renew. An explicit VM start then advances the provisioning generation through worker-owned fresh-machine recovery. The new raw credential travels only in the Fly machine environment and is persisted immediately in gateway-owner-only state; the old gateway and credential authority are revoked before the new generation becomes authoritative.

For shell_exec.secret_env, the gateway RPC proves the gateway's exact VM and current provisioning row plus consumed-bootstrap-token lineage for that exact generation. The mutable linked-gateway readiness projection is insufficient on its own. Children receive KDK-derived pano_sec_… aliases bound to that VM generation—not the stable database placeholder and never plaintext. Aliases survive an intentional stop/start and Team Secret value rotation, while reprovision or restore generation advancement replaces them so saved durable-home aliases cannot regain authority.

Runtime Structure

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

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/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.

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 mode is scoped by VM identity.

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.
• Managed VM guests run a scoped gateway and can invoke explicit Drive transfer commands through the Panorama CLI.

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; machine_control=true on remote_shell resources, stored as metadata.full_control)
• 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 mode:

• Guest gateway processes run with scoped VM identity.
• The agent runtime does not receive paired-user gateway session material.
• Drive contents are not mounted or watched. Uploads and downloads are explicit, bounded CLI operations authenticated as the VM-linked runtime principal. A command rejects files over 128 MiB and folders over 256 MiB, 200 files, 100 directories, or depth 32; agents must exclude, archive, or split larger work.
• The gateway owns /run/panorama/vm-runtime.sock and exposes only that socket path to shell children. The socket permits the bounded Drive operations used by the CLI; access tokens and object-storage credentials remain gateway-owned. The agent has group connect permission on the socket but not write permission on its parent directory, so it cannot replace the bridge endpoint.
• VM shell access is shared. Commands from different authorized agents use the same local execution account and the VM owner's Drive-transfer authority; the VM is not a per-command privacy boundary.

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

panorama-gateway start requires paired local gateway state. Managed VM guests receive scoped runtime credentials through the bootstrap exchange. 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.