PacketSafari Ops CLI · Documentation

packetsafari-ops is the host-side operator tool for installing, onboarding, tuning, upgrading, rolling back, inspecting, and troubleshooting PacketSafari on-prem deployments.

The web UI can show deployment state and copy supported commands, but privileged install and update actions run on the host.

Where it lives

Fresh installs place the wrapper at:

/opt/packetsafari/bin/packetsafari-ops

The wrapper runs the managed Python operator bundle under /opt/packetsafari/tooling/onprem.

Common workflows

Fresh install with automatic VM sizing:

curl -fsSL https://raw.githubusercontent.com/oripka/packetsafari-onprem/main/bootstrap.sh | bash -s -- install --license /path/to/license-token.json --manifest ./release-manifest.json --size auto

Open the operator menu:

/opt/packetsafari/bin/packetsafari-ops tui

Complete onboarding from the terminal menu:

/opt/packetsafari/bin/packetsafari-ops tui

Check deployment state:

/opt/packetsafari/bin/packetsafari-ops status --json

Show managed runtime configuration:

/opt/packetsafari/bin/packetsafari-ops config show

Retune after resizing the VM:

/opt/packetsafari/bin/packetsafari-ops tune --profile auto --apply

View recent backend logs:

/opt/packetsafari/bin/packetsafari-ops diagnostics logs --container packetsafari-backend --since 15m --tail 200

Restart one service:

/opt/packetsafari/bin/packetsafari-ops diagnostics restart --service backend

Restart the egress proxy after changing corporate proxy or CA settings:

/opt/packetsafari/bin/packetsafari-ops diagnostics restart --service egress-ironproxy

Set a corporate upstream proxy and restart egress-ironproxy:

/opt/packetsafari/bin/packetsafari-ops config upstream-proxy \
  --proxy-url http://zscaler-proxy.customer.example:8080 \
  --no-proxy localhost,127.0.0.1,::1 \
  --restart

Upgrade from a new manifest:

/opt/packetsafari/bin/packetsafari-ops upgrade --manifest ./release-manifest.json

Rollback to the latest snapshot:

/opt/packetsafari/bin/packetsafari-ops rollback

Print the first-admin creation command:

/opt/packetsafari/bin/packetsafari-ops iam show-initial-admin-command --email admin@example.com

--size auto on install and tune --profile auto inspect the host vCPU count, RAM, and runtime disk. PacketSafari then writes deterministic sizing artifacts for container CPU limits, memory limits, Celery concurrency, backend uWSGI process settings, sharkd cache settings, Redis memory arguments, and PostgreSQL memory settings.

Use tune --profile auto to generate files without touching running containers. Use tune --profile auto --apply to recreate the stack with the generated compose override.

Explicit profiles are available when an operator wants to pin behavior:

/opt/packetsafari/bin/packetsafari-ops tune --profile small --apply
/opt/packetsafari/bin/packetsafari-ops tune --profile medium --apply
/opt/packetsafari/bin/packetsafari-ops tune --profile large --apply

Use --profile none --apply to remove the managed sizing override and return to the base compose resources.

Command reference

Command	Purpose	Safe anytime?	Mutates state?
`status --json`	Inspect install, deployment, helper, backup, and sizing state.	yes	no
`tui`	Launch the terminal operator menu.	yes	maybe
`onboard schema`	Fetch onboarding schema, draft, license, and bootstrap status.	yes	no
`onboard validate`	Validate a pasted onboarding draft JSON payload.	yes	no
`onboard save-draft`	Save an onboarding draft JSON payload.	with care	yes
`onboard finalize`	Finalize onboarding and write managed runtime settings.	no	yes
`config show`	Print the managed runtime env.	yes	no
`config upstream-proxy`	Set or clear the corporate upstream proxy used by `egress-ironproxy`.	with care	yes
`tune --profile auto`	Generate host-sized runtime env and compose override files.	yes	yes
`tune --profile auto --apply`	Generate sizing files and recreate containers with the new limits.	with care	yes
`diagnostics logs`	Show recent container logs.	yes	no
`diagnostics restart`	Restart the full stack or a single service.	with care	yes
`install --size auto`	Fresh install with automatic host sizing.	no	yes
`upgrade`	Apply a new release manifest.	no	yes
`rollback`	Restore the latest snapshot and restart the stack.	no	yes
`iam show-initial-admin-command`	Print the backend command for first-admin creation.	yes	no
`iam set-password`	Run the backend password maintenance helper.	with care	yes

Runtime files

The default host runtime root is /opt/packetsafari.

/opt/packetsafari/state/ stores deployment state, release manifests, license material, helper status, and sizing.json.
/opt/packetsafari/env/runtime.env stores managed deployment settings.
/opt/packetsafari/env/ironproxy.env stores egress-proxy-only settings such as upstream OpenAI/Paddle/mail secrets and optional corporate upstream proxy variables.
/opt/packetsafari/env/runtime-sizing.env stores generated sizing env values.
/opt/packetsafari/configuration/custom-ca/ stores customer root CAs loaded into egress-ironproxy, including corporate TLS inspection CAs.
/opt/packetsafari/compose/docker-compose.onprem.yml stores the rendered base compose file.
/opt/packetsafari/compose/docker-compose.sizing.yml stores generated resource limits and sizing overrides.
/opt/packetsafari/backups/ stores upgrade snapshots used by rollback.

Corporate upstream proxy configuration

If the customer network requires Zscaler or another outbound proxy, configure it with:

/opt/packetsafari/bin/packetsafari-ops config upstream-proxy \
  --proxy-url http://zscaler-proxy.customer.example:8080 \
  --no-proxy localhost,127.0.0.1,::1 \
  --restart

The command writes /opt/packetsafari/env/ironproxy.env. Use --http-proxy and --https-proxy instead of --proxy-url only when the customer requires different upstream proxies per scheme.

To remove a corporate upstream proxy:

/opt/packetsafari/bin/packetsafari-ops config upstream-proxy --clear --restart

Keep backend and worker pointed at PacketSafari's internal proxy by leaving PACKETSAFARI_EGRESS_PROXY_URL as http://egress-ironproxy:10000.

For TLS inspection, place the corporate root CA in /opt/packetsafari/configuration/custom-ca/ and restart egress-ironproxy. PacketSafari supports standard HTTP proxy chaining through HTTP_PROXY and HTTPS_PROXY; PAC files, NTLM/Kerberos proxy auth, and SOCKS-only upstream proxies are not first-class packetsafari-ops configuration today.

Troubleshooting

License validation failures usually mean the token is missing, expired, malformed, or signed by a different key than the bundled public key.

Missing required env keys during upgrade mean the target release manifest declares new requiredEnv values. Complete onboarding or edit the managed runtime env before retrying.

Image pull failures are host Docker or registry access issues. Confirm the digest-pinned image references in the manifest are reachable from the host.

Onboarding finalize issues usually come from missing required provider, identity, mail, or generated-secret fields. Use tui to load the schema and validate the draft before finalizing.

AI provider and egress approval failures usually require checking the selected provider mode, shared API key, approved destination host, and private CA trust configuration.

For running Agent investigations from a terminal or API client, see Headless Agent API and CLI. That client uses the backend Agent API and is separate from the host-side packetsafari-ops deployment tool.