Framework plugins

The framework plugins put AegisRunner inside your dev server. Add one line to your Vite, Nuxt or Next config, run your normal dev command, and an AI scan of your localhost app is one keypress away — no deploy, no staging URL, no second terminal.

They’re all built on the same primitive, so pick whichever fits your stack:

How it works

By default the plugins run the scan entirely on your machine: a real browser (@aegisrunner/scan-runner) drives your app at http://localhost directly — no tunnel, no cloud relay. It’s the fastest and most reliable path for big apps (hundreds of routes, Vite’s unbundled module bursts), and your app and any credentials never leave your machine. The first scan fetches the browser (Chromium, ~150 MB, then cached); no Docker required.

Prefer to relay our cloud browser over a secure outbound tunnel instead — nothing to install locally? Set runner: ‘tunnel’. The plugin opens an outbound-only connection from your machine (no inbound port), giving a temporary <id>.tunnel.aegisrunner.com URL the cloud scanner reaches. See Testing behind a firewall for how the tunnel is secured.

Either way, a scan runs a full crawl + test generation and streams progress into your dev log. The runner lifecycle, tunnel client, scan trigger and live-progress stream all come from @aegisrunner/cli, so the protocol and auth live in exactly one place.

The in-app widget

A floating AegisRunner shield is injected into every dev page. Click it to:

• Test this page — scan just the current route.
• Test the whole site — a full AI crawl + test generation.
• Run generated tests — execute your latest generated suite (in local mode the browser runs on your machine; verdicts match a cloud run).
• Login credentials — set a username/password so gated pages get scanned (in local mode they stay on your machine).

…with live progress and a link to the results, without leaving the app you’re building. You can still press [a] in the terminal, or scan automatically with scanOn: ‘startup’. Pass widget: false to turn it off. In Nuxt, the same status also appears in a native DevTools tab.

Notes for local mode

A couple of things to know about the default runner: ‘local’ — switch to runner: ‘tunnel’ if either matters to you:

• The first scan installs a browser. Local mode runs a real headless Chromium on your machine via @aegisrunner/scan-runner; the first scan downloads it (~150 MB) and caches it. No Docker required.
• One scan at a time per project. The local runner claims jobs from your project’s queue, so run one dev server’s scan at a time per project. If you scan several dev servers at once — a monorepo running many apps — use runner: ‘tunnel’, which keeps each one isolated. (We’re lifting this limit.)

Vite — React, Vue, Svelte, Solid…

One plugin covers the whole Vite ecosystem. A React app on Vite and a Vue app on Vite both use this exact package — there’s no separate @aegisrunner/react or @aegisrunner/vue. (On Next.js use @aegisrunner/next; on Nuxt use @aegisrunner/nuxt.)

npm install -D @aegisrunner/vite

// vite.config.js  — React, Vue, Svelte, Solid, … (any Vite app)
import { defineConfig } from 'vite'
import aegis from '@aegisrunner/vite'

export default defineConfig({
  plugins: [
    aegis({
      token: process.env.AEGIS_TOKEN,   // your project CI token — see "Your token" below
      scanOn: 'manual',                 // 'manual' (press a / click) | 'startup'
    }),
  ],
})

React (Vite) and Vue (Vite) are identical to the above — the plugin injects the widget into your dev HTML regardless of the UI framework. Don’t paste the token literal into a committed config; read it from the environment (process.env.AEGIS_TOKEN) or run aegis login once and drop the option entirely.

Nuxt (Vue)

A Nuxt module, plus a native DevTools tab showing live tunnel + scan status and a one-click Scan now. Use this for Vue apps built on Nuxt; a plain Vite + Vue app uses @aegisrunner/vite instead.

npm install -D @aegisrunner/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@aegisrunner/nuxt'],
  aegis: {
    token: process.env.AEGIS_TOKEN,   // or run `aegis login` once (see "Your token")
    scanOn: 'manual',
  },
})

Next.js (React)

Next has no dev-server plugin hook, so you wrap your config. It attaches AegisRunner in the dev phase only — a pure pass-through in next build / production — and injects the widget via a dev-only rewrite.

Next 16 (Turbopack): next dev runs on Turbopack by default in Next 16, which the widget can’t auto-inject into. Everything still works — scans, [a], and the widget’s endpoints — but to show the floating shield, either add <script async src=”/__aegis/widget.js”></script> to your root layout (dev only), or run next dev —webpack.

npm install -D @aegisrunner/next

// next.config.mjs
import withAegisRunner from '@aegisrunner/next'

const nextConfig = { /* your config */ }
export default withAegisRunner(nextConfig, {
  token: process.env.AEGIS_TOKEN,   // or run `aegis login` once (see "Your token")
  scanOn: 'manual',
})

Any framework — aegis dev

The universal wrapper. It spawns your dev command, opens the tunnel, and gives you an interactive scan — no config change at all.

npm install -g @aegisrunner/cli
aegis dev --port 3000 -- npm run dev

While it runs: [a] scan · [o] open results · [q] quit.

Your token

Every plugin needs a project CI trigger token (create one under Manage → CI/CD, Pro or Business plan). You have three ways to supply it — pick one. Never paste the token literal into a committed config file.

1. aegis login (recommended) — save it once; every command and the dev widget/plugins read it automatically, so you can drop the token option entirely:

npm i -g @aegisrunner/cli
aegis login --token aegis_xxxxxxxx     # or:  printf %s "$TOKEN" | aegis login
# saved to ~/.config/aegis/config.json (mode 0600). Remove it with: aegis logout

2. Environment variable — the plugins default to process.env.AEGIS_TOKEN, so this needs no config at all. Keep it in a git-ignored .env your dev server loads, or export it in your shell:

export AEGIS_TOKEN=aegis_xxxxxxxx
npm run dev

3. The token option — pass it explicitly in the config, reading from the environment (or your own secrets loader). This is the form shown in each framework example above:

aegis({ token: process.env.AEGIS_TOKEN })      // vite.config
// nuxt.config:  aegis: { token: process.env.AEGIS_TOKEN }
// next.config:  withAegisRunner(cfg, { token: process.env.AEGIS_TOKEN })

Precedence is token option → AEGIS_TOKEN env → the saved aegis login file, so a flag or env always wins (CI stays unaffected).

All options

All plugins take the same options (and aegis dev the matching flags):

Monorepos

Running several dev servers at once (e.g. turbo dev fanning out apps into one terminal)? Each app opens its own tunnel, and every log line is tagged with a label — by default the package name — so you can tell them apart:

[aegis·web]   tunnel open → https://ab12.tunnel.aegisrunner.com
[aegis·admin] tunnel open → https://cd34.tunnel.aegisrunner.com

Override it with the label option (or aegis dev —label).

Gate your pushes — aegis hooks

Want a scan (or your test suite) to run before code leaves your machine? Install an opt-in pre-push git hook that blocks git push on failure:

aegis hooks install     # gate = aegis run --wait  (uninstall: aegis hooks uninstall)

Nothing is installed until you run it, and an existing pre-push hook is backed up rather than clobbered.

Requirements

• A project CI trigger token — create one under Manage → CI/CD (Pro or Business plan).
• Node 18+. The plugins are dev-only and never run in a production build.

Related

• Test a localhost app — the overview.
• Testing behind a firewall — the tunnel, allowlist and self-hosted runner.
• CI/CD Integration — the same token, from your pipeline.