Configuration and API reference#

PacketAgent is configured primarily through environment variables. Keep production values in the deployment secret store and change one subsystem at a time.

Before you start#

• Identify whether the installation uses SQLite or managed PostgreSQL.
• Record the current application and preview origins.
• Back up the deployment variables without printing their values.
• Test changes on a non-production Worker before restarting production.

Core runtime#

Generate and supply independent secrets for the vault, preview capability tokens, tool approvals, webhook delivery, and rate-limit key hashing. Do not use fallback development values in a reachable installation.

Registration and access#

Self-service registration is invite-only. The first registration on an empty store is allowed and becomes the owner of a new workspace; every later account must present an invitation issued to the same email address.

open restores unrestricted sign-up and suits only a trusted network. Any other value stops registration with a server error instead of falling back to a default.

Warning: with open, anyone who can reach the service can create an account and a workspace.

A workspace admin or owner creates invitations through the API. The workbench lists, resends, and revokes invitations, but it does not create them. $CSRF_TOKEN is the packetagent_csrf cookie value set at sign-in, as described under API conventions below.

curl -fsS -X POST "$PACKETAGENT_URL/api/app/invitations" \
  -b cookies.txt -c cookies.txt \
  -H 'content-type: application/json' \
  -H "x-csrf-token: $CSRF_TOKEN" \
  -d '{"email":"person@example.com","role":"member"}'

Supported roles are viewer, member, admin, and owner; only an owner may invite an owner. The response returns the invitation token once — later reads show a masked preview. Send the recipient /sign-up?invite=<token>, which fills the Invitation code field on the sign-up form. Invitations expire seven days after they are created or resent, and one token admits exactly one account: the new user joins the inviting workspace with the invited role as the account is created.

Every new account also receives a workspace of its own and owns it, whether it registered as the bootstrap account or on an invitation. Someone invited as viewer is a viewer in your workspace and an owner in theirs. Plan for that if workspace creation is something you meter or audit.

Unknown, expired, revoked, already-used, and mismatched tokens all return the same 403, so a rejected sign-up does not confirm which addresses were invited.

Provider routing#

PacketAgent can route through Anthropic, OpenAI, OpenRouter, MiniMax, Gemini, and Ollama or another OpenAI-compatible endpoint reached through the local-LLM base URL, when the corresponding credentials and base URLs are configured. The local option is one target, not two: point LOCAL_LLM_BASE_URL or OLLAMA_BASE_URL at Ollama or at any OpenAI-compatible server. Provider availability does not prove that a requested model exists; verify each routing preset with a controlled request.

Sandbox and scheduler#

PACKETAGENT_SANDBOX_* settings control runtime, time, memory, CPU, process, temporary-storage, and outbound-network limits. Begin with Docker, deny outbound network access, and allow exact origins only.

PACKETAGENT_SCHEDULER_LEADER_MODE selects no coordination (off), a file lock, or HTTP coordination. off does not disable scheduled work; every replica can schedule, so use it only with one replica. Use exactly one scheduler leader for every store population when running multiple replicas.

API conventions#

These entry points accept a request without a session cookie. Review the whole list when hardening an installation, because network restrictions have to be placed with all of it in view, not only the health checks.

The /api/public/share and /api/public/webhooks routes carry their credential in the URL. Do not log those paths in full, do not paste them into ticket systems, and reissue a webhook reference whenever its Worker's webhook token is rotated.

Authenticated application routes use the session cookie. State-changing routes also require the CSRF cookie value in the x-csrf-token header. API clients should use a cookie jar rather than copying values into scripts.

Packet-product credentials#

Current source builds accept PacketBench, the legacy PacketADE identity, and PacketChat as Worker-package source identities. Choose the identity that matches the sending product. A PacketChat connection uses a workspace-bound PacketChat credential:

node --import tsx src/db/cli.ts packet-product-credential issue \
  --workspace <workspace-id> --product PacketChat \
  --operations deployment.inspect,deployment.activate

Run the command in the PacketAgent source checkout with the production store configuration supplied through protected environment variables. The token is printed once; capture it directly into the destination's secret store. Tokens use pkbench, pkade, or pkchat prefixes for their corresponding product. The PacketChat connection needs deployment.inspect and deployment.activate. Keep package-publishing operations on a separate publisher credential.

For signature-required packages, register the publisher's Ed25519 public key with packet-product-signing-key add and the matching --product before issuing a credential with --require-signature. Never pass a private signing key to the registry. Keep the package source identity, credential identity, workspace and registered signing-key scope aligned.

Prepare a deployment for PacketChat#

PacketChat starts runs through the Packet-product API. Prepare a deployment created from a validated WorkerPackage in the same workspace, using a publisher credential permitted to package.validate and package.deploy. An ordinary deployment created only through the Worker workbench does not provide this package binding.

The authenticated GET /api/worker-packages/contract describes accepted source identities, operations and signing requirements. Validate an exported package through POST /api/worker-packages/validate, then create its deployment through POST /api/worker-deployments and record the returned deployment id. Package writes require an Idempotency-Key and the workspace header as well as the publisher bearer token. Include an enabled manual trigger in the immutable Worker version: PacketChat requests a new run without selecting a trigger id. Configure the packetchat notification route before publishing that version.

Enter that deployment id and the restricted PacketChat credential in the PacketChat project connection. A failed lookup usually means the workspace, package binding or inspection permission is wrong; failed activation can also mean the version has no enabled manual trigger.

Verify#

1. Restart the process and confirm no startup validation error.
2. Check both health endpoints.
3. Sign in through a new session.
4. Validate one Worker version in Docker.
5. Run one manual trigger and inspect its usage and policy record.

Related#

• Deploy — production topology and hardening.
• Troubleshooting — startup and runtime errors.