Panorama Gateway

Gateway service for connecting CLI capabilities on a host machine to a Panorama team. A team can pair multiple gateways from different machines; each gateway instance is identified by its own gateway_id.

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 install-level full-control on this host:

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

Execution and Security Model

• Gateway processes run as the logged-in user and are designed to behave like direct local CLI usage.
• Provider child processes inherit user environment semantics, but gateway-internal secrets are scrubbed before launch.
• Provider/runtime isolation relies on built-in provider controls (for example Codex read-only sandbox + tool flags), not heavyweight host isolation.
• Machine-control capabilities are layered:
  • install-level host toggle (panorama-gateway full-control enable)
  • team-level gateway 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).

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 runtime 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 gateway subagents
• shell_session jobs for remote shell sessions (open, write, read, status, close) 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.

CLI Provider Notes

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