# Development

URL: https://docs.vaultpanel.net/developers/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.

This page is for working on VaultPanel itself. To run the panel on a server, use the [installer](https://docs.vaultpanel.net/getting-started/installation).

## 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

```bash
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

```bash
cp .env.example .env
```

Set `VAULTPANEL_SECRET_KEY` to 32 random bytes:

```bash
openssl rand -hex 32
```

### Install and migrate

```bash
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:

```bash
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:

```bash
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.

> **Note:**
Started as root on Linux with systemd, `npm run dev:backend` connects the machine it runs on as a server and installs the agent as a service from `agent/dist`, so put a build there first:

```bash
mkdir -p agent/dist && cp agent/target/release/vaultpanel-agent agent/dist/vaultpanel-agent-x64   # or -arm64
```

Set `VAULTPANEL_LOCAL_AGENT=false` in `.env` to stop the automatic connection.

### 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:

```bash
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

```bash
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](https://docs.vaultpanel.net/developers/development#the-agent).

> **Warning:**
`npm test` uses `.env.test` (database `vaultpanel_test`, Redis database 15), and the backend suite rebuilds `vaultpanel_test` from scratch. Never point `.env.test` at real data. The end-to-end tests use their own databases, `vaultpanel_e2e` and `vaultpanel_e2e_tls`.

## npm scripts

| Script | Does |
| --- | --- |
| `dev:backend` | The API in watch mode. |
| `dev:worker` | The worker in watch mode. |
| `dev:frontend` | The Vite development server. |
| `build` | Builds the interface into `frontend/dist`. |
| `lint` | ESLint over the repository. |
| `test` | Every workspace's tests. |
| `db:migrate`, `db:rollback` | Applies or rolls back migrations. |
| `connect-local` | Connects the machine the panel runs on as a server (run as root). |
| `cli` | Runs the `vaultpanel` CLI from the checkout. |
| `test:e2e`, `test:coverage` | End-to-end tests; tests with coverage. |
| `test:conformance` | Checks 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](https://docs.vaultpanel.net/developers/agent#upgrading).
