PacketAgentDocs

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#

Variable Typical value Purpose
NODE_ENV production Enables production secret and cookie requirements.
PORT 8484 HTTP listener.
PACKETAGENT_STORE sqlite or postgres Selects persistence.
PACKETAGENT_DB_PATH durable file path SQLite database location.
DATABASE_URL deployment secret Managed PostgreSQL connection.
PACKETAGENT_APP_ORIGIN public HTTPS URL Main workbench origin.
PACKETAGENT_PREVIEW_ORIGIN separate HTTPS URL Generated-app preview origin.
PACKETAGENT_SANDBOX_DRIVER docker Worker code-execution boundary.

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.

Variable Default Purpose
PACKETAGENT_REGISTRATION_MODE invite_only Requires a workspace invitation for each account after the first.

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.

Method and path Purpose
GET /api/health Process liveness
GET /api/health/live Process liveness, alternate path
GET /api/health/ready Store and runtime readiness
POST /api/auth/register Create the bootstrap account, or an invited account with invitationToken
POST /api/auth/login Start a browser/API session
GET /api/activation Public activation summaries for every workspace
GET /api/activation/:workspaceId Public activation summary for one workspace
GET /api/public/share/:token Opens a shared record; the token in the path is the only credential
POST /api/public/webhooks/workers/:webhookRef Delivers a Worker webhook trigger; the reference in the path is the only credential
POST /api/public/webhooks/agents/:token Delivers a legacy Agent webhook trigger; the token in the path is the only credential
POST /api/public/webhooks/invitation-email Accepts invitation-email delivery results; authorised by a shared secret header

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.

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.