PacketAgentDocs

Deploy PacketAgent#

PacketAgent can serve its built web application, API, scheduler, and Worker control plane from one process. The repository Docker setup adds a Docker-backed sandbox and persistent application data.

Before you start#

  • Choose the application HTTPS origin and a different HTTPS origin for generated previews.
  • Generate independent production secrets for the vault, preview tokens, tool approvals, and rate-limit key hashing.
  • Choose SQLite for one process or PostgreSQL for a managed, multi-instance deployment.
  • Decide whether the host may safely expose its Docker socket to the PacketAgent container. Use a dedicated host or stronger isolation when it may not.

Build and run one process#

npm ci
npm run build:web
npm run build:server
npm start

The process listens on PORT, default 8484. Set NODE_ENV=production so production secret and origin checks are enforced.

Run with Docker Compose#

  1. Store secrets in the deployment platform or a protected environment file.

  2. Set at least:

    • NODE_ENV=production
    • MASTER_KEY
    • PACKETAGENT_TOOL_APPROVAL_SECRET
    • PACKETAGENT_RATE_LIMIT_KEY_SALT
    • PACKETAGENT_APP_ORIGIN
    • PACKETAGENT_PREVIEW_ORIGIN
    • the selected store and database path or URL

  3. Add the approval secret to the committed Compose service; the current file does not pass it through:

    environment:
  PACKETAGENT_TOOL_APPROVAL_SECRET: "${PACKETAGENT_TOOL_APPROVAL_SECRET:?set a long random secret}"

  4. Keep application and preview hostnames different.

  5. Mount /app/data on durable storage when using SQLite.

  6. Start the Compose stack and review startup output before exposing traffic.

Generated artifacts are not served unless explicitly enabled. Keep that default until an authenticated download path and retention policy have been reviewed.

Harden the deployment#

  • Terminate TLS before the application and preview origins.
  • Trust forwarded client addresses only when an edge you control is the sole route to the service.
  • Use the Docker sandbox in production and start with no outbound network allowlist.
  • Restrict registration or network reach according to the installation’s access policy; the current registration endpoint is open to reachable callers.
  • Back up the store and all generated-app, published-app, and artifact paths.
  • Configure scheduler leadership before running more than one instance.

Verify#

test -n "$PACKETAGENT_URL" || { echo "Set PACKETAGENT_URL to the deployed origin" >&2; exit 1; }
curl -fsS "$PACKETAGENT_URL/api/health/ready"

Also verify:

  1. The app and preview origins are different and both use HTTPS.
  2. Restarting the service preserves account and Worker data.
  3. A sandboxed validation runs in Docker and cannot reach an unapproved origin.
  4. A fresh browser can register only according to the intended access policy.
  5. One controlled Worker run completes and appears in operations history.

If it does not work#

Symptom Check
Startup names a missing secret Supply a new deployment secret; do not use development defaults.
Startup rejects origins Use two different absolute HTTPS origins.
Data disappears after restart Mount the selected SQLite path or correct the PostgreSQL URL.
Preview fails while the app works Check preview DNS, TLS, origin configuration, and capability-token secret.
Multiple instances duplicate scheduled work Configure a single leader or run one scheduler instance.