Development

Run VaultPanel from source for development — MariaDB and Redis in Docker, the API, worker and interface in watch mode, the checks CI runs and the code conventions.

Last updated

This page is for working on VaultPanel itself. To run the panel on a server, use the installer.

Requirements

  • Node.js 22 or newer, for the panel.
  • MariaDB 10.6 or newer (or MySQL 8) and Redis 6.2 or newer. Docker can provide both.
  • To work on the agent, or to connect a server to a panel run from a checkout: Rust, on the toolchain CI uses (RUST_VERSION in .github/workflows/agent.yml), and a C compiler for the TLS crates (build-essential on Debian and Ubuntu). The agent builds and runs on Linux only.

Set up

Start MariaDB and Redis

docker compose -f docker/compose.yml up -d

This starts MariaDB on 127.0.0.1:3307 (creating the vaultpanel and vaultpanel_test databases) and Redis on 127.0.0.1:6379. The containers restart after a reboot as long as Docker starts at boot.

Configure

cp .env.example .env

Set VAULTPANEL_SECRET_KEY to 32 random bytes:

openssl rand -hex 32

Install and migrate

npm install
npm run db:migrate

db:migrate applies the migrations, then syncs the built-in roles and permissions from shared/src/permissions.js.

Run the API, the worker and the interface

In three terminals:

npm run dev:backend   # API on http://127.0.0.1:4000 (prints the setup token)
npm run dev:worker    # background maintenance and the AI assistant
npm run dev:frontend  # UI on http://localhost:5173, proxies /api to the backend

Create the owner

Open http://localhost:5173/setup and create the owner account with the setup token from the API log.

HTTPS locally

To try the panel with HTTPS as the installer runs it, make a certificate and set VAULTPANEL_TLS_CERT, VAULTPANEL_TLS_KEY (and optionally VAULTPANEL_LOOPBACK_PORT) in .env. The end-to-end test script e2e/scripts/start-panel.js https shows the whole setup.

The agent

The agent is written in Rust, in agent/. Build and check it there:

cd agent
cargo build --release          # target/release/vaultpanel-agent
cargo test
cargo fmt --check
cargo clippy --release --all-targets -- -D warnings

./agent/scripts/dev-build.sh builds it without downloading crates, with rustc alone, into agent/build/vaultpanel-agent (it needs libssl-dev). That build has no TLS, so it only reaches a panel over loopback HTTP: it is for development, never for servers.

From the repository root, npm run test:conformance checks the agent against the protocol (docs/agent-protocol.md in the repository). It uses the release build, else the development build; AGENT_CMD names another. agent/README.md has the rest: the static release builds, the layout of the sources and how this agent differs from the Node.js one it replaced.

Running an agent by hand

To run an agent without installing a service, add a server in the interface, then register and run it from the checkout:

agent/build/vaultpanel-agent register --panel http://localhost:5173 --token vpe_… --config ./tmp/agent.json --insecure-http
agent/build/vaultpanel-agent run --config ./tmp/agent.json

--insecure-http is for local development only; the panel must also allow it with VAULTPANEL_ALLOW_INSECURE_AGENTS=true (the default in .env.example).

Repository layout

install.sh and scripts/ hold the installer, the agent installer and the vaultpanel server command. Tests live next to each package (backend/test, shared/test, frontend/src/**/*.test.js), so each package runs its own suite. The agent's tests are Rust unit tests next to its code (cargo test), and conformance/ checks it against the protocol from the outside.

Checks

npm run lint
npm test                # needs MariaDB and Redis
npm run build
npm run test:coverage   # the same tests, with a coverage summary per package
npm run test:e2e        # end-to-end smoke tests in a browser
npm run test:conformance   # the agent against the protocol (build it first)

npm test runs the tests of the npm workspaces; the agent is not one of them. Its checks are the cargo commands above.

npm scripts

ScriptDoes
dev:backendThe API in watch mode.
dev:workerThe worker in watch mode.
dev:frontendThe Vite development server.
buildBuilds the interface into frontend/dist.
lintESLint over the repository.
testEvery workspace's tests.
db:migrate, db:rollbackApplies or rolls back migrations.
connect-localConnects the machine the panel runs on as a server (run as root).
cliRuns the vaultpanel CLI from the checkout.
test:e2e, test:coverageEnd-to-end tests; tests with coverage.
test:conformanceChecks the agent against the protocol.

Conventions

  • JavaScript (ES modules) for the panel, Rust for the agent.
  • Business rules live in services, not controllers. Services take an actor, check permissions through services/authorization.js and record audit entries.
  • Every response uses the envelope { success, data, message, requestId }, and every error an AppError with an HTTP status and a stable code.
  • The panel's development MariaDB is on port 3307, not 3306, so a MariaDB installed for apps on the same machine can use the standard port.

Adding an agent operation

A new operation is added in three places, and a backend test fails if the panel offers an operation the agent does not implement:

  1. The catalog, shared/src/operations.js: its name, label, permission, parameters, whether it is dangerous or retryable, and its timeout.
  2. The agent, OPERATIONS in agent/src/ops/mod.rs, with the implementation in agent/src/ops/: fixed commands and no shell.
  3. A test.

A rule the agent checks again (a pattern in shared/) also goes into agent/src/ops/rules.rs; conformance/rules.test.js fails when the two disagree.

Agents report the operations they support, so older agents answer AGENT_OUTDATED for the new one until they are upgraded.