Reference

Configuration

Nuxt module options, defineNuxtAgentic, the Void plugin, defineVoidAgentic and environment variables.

Nuxt module options

Set under agentic in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  extends: ['@nuxtagentic-pro/nuxt'],
  agentic: {
    dashboard: { path: '/app' },
    features: { localRuntimes: false },
  },
})

Option	Default	Description
`basePath`	`'/api/agentic'`	Mount path of the Agentic API
`dashboard.path`	`'/dashboard'`	Mount path of the dashboard
`features`	`{}`	Switch optional features off; see Features
`modelsDir`	`'server/models'`	Agentic Models, scanned in the app and every layer
`toolsDir`	`'server/tools'`	`defineAgentTool` tools
`agentsDir`	`'server/agents'`	Markdown agents
`automationsDir`	`'server/automations'`	`defineAutomation` templates
`integrationsDir`	`'server/integrations'`	`defineIntegration` integrations
`configFile`	`'server/agentic'`	The optional `defineNuxtAgentic` module
`cron`	`'/5 * * *'`	Schedule of the maintenance pass
`localRuntimes`	`true`	Local Codex CLI and Claude Code runtimes in `nuxt dev`; `false` or `{ binaries, environment }`
`localMcp`	`true`	Let `agentic mcp` connect coding agents to `nuxt dev`
`route`	`'/api/_agentic'`	Prefix of the free module's `useAgent()` endpoint

Keep basePath at /api/agentic when you use the dashboard: the dashboard and the layer composables call that path. Local runtimes and local MCP only run while the dev server listens on localhost and are never part of a build.

defineNuxtAgentic

server/agentic.ts configures what is not discovered from files:

server/agentic.ts

export default defineNuxtAgentic({
  auth: {
    socialProviders: {
      github: {
        clientId: process.env.GITHUB_CLIENT_ID!,
        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      },
    },
  },
})

Option	Description
`auth`	better-auth options such as `socialProviders`, `plugins` and plugin `tables`; database and secret come from the app
`features`	Extra features from `defineFeature`, registered after the built-in ones
`models`	Extra Agentic Models registered in code
`tools`	Extra tools registered in code
`integrations`	Extra integrations registered in code
`updateRecord`	Trusted outcome adapter for tables that are not Agentic Models; see Outcomes

Void plugin

vite.config.ts

plugins: [...(await voidAgentic({ server: 'src/agentic.ts' })), vue(), voidPlugin()]

Option	Default	Description
`server`		Module that default-exports `defineVoidAgentic(...)`
`localRuntimes`	`true`	Local Codex CLI and Claude Code runtimes in `vite dev`
`localMcp`	`true`	Let `agentic mcp` connect coding agents to `vite dev`
`schema`	`true`	Generate `db/schema.ts`; disable only when you compose it yourself
`auth`	`true`	Generate the auth config; disable only when you compose `withAgenticAuth`
`maintenance`	`true`	Add the maintenance cron; disable only when you run `runVoidMaintenance` yourself
`ui`	`true`	Install the Nuxt UI Vite plugin

defineVoidAgentic

src/agentic.ts defines the backend for the API, crons and Durable Objects:

Option	Description
`models`	Agentic Models
`tools`	`defineAgentTool` tools
`integrations`	`defineIntegration` integrations
`features`	The feature list; defaults to `defaultFeatures()`
`events`	Event handler; see Events
`updateRecord`	Trusted outcome adapter
`basePath`	Mount path of the API, default `/api/agentic`
`dashboardPath`	Mount path of the dashboard, default `/dashboard`
`openapi`	`title`, `version` and `description` of the OpenAPI document

Environment variables

Set these in .env for development and as Worker secrets in production.

Variable	Description
`BETTER_AUTH_SECRET`	Required. Signs sessions
`BETTER_AUTH_URL`	The app's public URL, required in production (Nuxt)
`AGENTIC_ENCRYPTION_KEY`	Required. 32 bytes, base64; encrypts integration credentials
`OPENAI_API_KEY`	Provider key for OpenAI agents
`ANTHROPIC_API_KEY`	Provider key for Anthropic agents
`GOOGLE_AI_API_KEY`	Provider key for Google agents
`AGENTIC_DECISION_PROVIDER`	Prompt planner: `typesafeAI` (default) or `openAI`
`AGENTIC_DECISION_MODEL`	Prompt planner model override
`TYPESAFE_API_KEY`	Key for the `typesafeAI` planner
`AGENTIC_<PROVIDER>_CLIENT_ID`, `AGENTIC_<PROVIDER>_CLIENT_SECRET`	OAuth app for an integration provider, such as `AGENTIC_GOOGLE_CLIENT_ID`
`AGENTIC_WEBHOOK_ORIGINS`	Comma-separated HTTPS origins that webhook outcomes may call
`AGENTIC_MCP_ORIGINS`	Comma-separated HTTPS origins of allowed MCP servers
`AGENTIC_MCP_AUTH_ORIGINS`	MCP authorization servers on another origin
`AGENTIC_MCP_CLIENTS`	JSON map of MCP server URL to pre-registered OAuth client
`AGENTIC_RUN_RETENTION_DAYS`	Archive finished agent and automation runs after N days; `0` (default) keeps them
`AGENTIC_APPROVAL_RETENTION_DAYS`	Archive answered approvals after N days; `0` (default) keeps them
`AGENTIC_RECEIPT_RETENTION_DAYS`	Remove automation delivery receipts after N days; default `1`
`AGENTIC_IMAGE_RETENTION_DAYS`	Delete unused profile images and logos after N days; `0` (default) keeps them

Retention values are whole days from 0 to 3650.

Upgrading

Update to a new release or move from the free module to Pro.

Composables

Nuxt composables for durable agents, runs, automations, the workspace and the API client.