PacketAgentDocs

Install PacketAgent locally#

Run PacketAgent from a source checkout to evaluate the workbench and build a test Worker. This local setup is not a production deployment.

Before you start#

  • Install Node.js 22.5 or newer and npm.
  • Install Git.
  • Install Docker if Worker validation or sandboxed execution will be tested.
  • Reserve ports 8484 for the API and 7341 for the development web client.

Install and start#

  1. Clone the repository and enter its root.

    git clone https://github.com/packetloss404/PacketAgent.git
cd PacketAgent

  2. Install the locked dependencies.

    npm ci

  3. Start the API and web development servers.

    npm run dev

  4. Open http://localhost:7341.

The workbench serves its own fonts and stylesheets from the application origin, so it renders correctly on a machine with no outbound internet access.

Create the first account#

Self-service registration is invite-only. The first registration on an empty store is always allowed and becomes the owner, so sign up with a test-only email and password to start the evaluation. Do not reuse development fixtures or their credentials in a reachable environment.

Every later account needs a workspace invitation. Issue the invitation from the workspace, then open its link: the token arrives as the invite query parameter and fills the Invitation code field on the sign-up form, which also accepts a pasted code. Accepting an invitation creates the account and joins the inviting workspace with the invited role in one step, and the token cannot be used again. Each new account also gets a workspace of its own and owns it, in addition to the invited membership.

For a local evaluation on a trusted machine, restore open registration:

PACKETAGENT_REGISTRATION_MODE=open npm run dev

PACKETAGENT_REGISTRATION_MODE accepts invite_only (the default) and open. Any other value stops registration with a server error.

Warning: open lets anyone who can reach the port create an account and a workspace. Keep the default on any reachable installation.

Choose local storage#

Set PACKETAGENT_STORE=sqlite and keep the default SQLite path for a durable single-machine evaluation. Mount or copy the data directory if the checkout itself is disposable.

JSON storage is useful only for narrow development scenarios. PostgreSQL is the multi-instance storage choice and requires the managed database configuration described in Configuration and API.

Add a provider#

Supply one supported provider credential through the deployment environment or the administrative secret workflow. Keep provider keys out of Worker text, browser storage, shell history, and committed files.

After startup, open the provider settings and confirm PacketAgent can resolve a model for the intended routing preset before running a Worker.

Verify#

curl -fsS http://127.0.0.1:8484/api/health
curl -fsS http://127.0.0.1:8484/api/health/ready

Then confirm:

  • the first registration and sign-in succeed;
  • the workbench opens;
  • the ready endpoint can load the selected store; and
  • Docker validation succeeds before using sandboxed Worker tools.

If it does not work#

Symptom Check
npm ci rejects the environment Upgrade Node.js to the required version.
Web page loads but API calls fail Confirm the API remains on port 8484 and inspect the development proxy output.
Ready returns 503 Check store selection, database URL or file path, migrations, and permissions.
Worker validation is blocked Start Docker and confirm the current user can run containers.
Sign-up is rejected with 403 The store already holds an account, so the instance is invite-only. Register with a valid invitation code or restart with PACKETAGENT_REGISTRATION_MODE=open.
Sign-up fails with a server error PACKETAGENT_REGISTRATION_MODE is set to something other than invite_only or open. Correct the value and restart.

Next#