npm package: @panorama-ai/gateway
Description: 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`.
Latest version: 2.29.14

# 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:

```bash
panorama-gateway pair <PAIRING_CODE>
```

For local package development:

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

Or pass backend overrides directly:

```bash
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):

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

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

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

Run in the foreground (built binary):

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

Stop this gateway:

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

Check this gateway's status:

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

Manage install-level full-control on this host:

```bash
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:

```bash
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.