Server AI Assistant

This guide installs Server AI Assistant A1.0.0, a permission-scoped AI assistant for the Pterodactyl server panel.

Back up the Panel database before installing or upgrading. Choose one package format — do not install the Ainx and Blueprint versions on the same Panel.

Requirements

Linux with PHP 8.2 or newer, Node.js 22 or newer, and Yarn.
Bubblewrap with usable unprivileged user namespaces — the installer fails closed when its isolation probe cannot run.
An asynchronous Laravel queue (Redis or database); the synchronous driver is not supported.
Codex CLI 0.144.6 or newer, only when customer ChatGPT-account mode is used. API-key providers do not need Codex.

Run the installer from the Panel root:

bash

ainx install aiassistant.ainx

Configuration

Open Admin → Extensions → Server AI Assistant after installation.

Set the assistant name, icon, approval policy, and history retention.
Choose customer-owned ChatGPT authentication or enable encrypted administrator API providers with exact model identifiers.
Configure token allowances, reset periods, concurrency, runtime resources, and the queue name.
Run the built-in diagnostics and confirm everything passes before exposing the assistant to customers.

First test: open one server with a restricted subuser. Confirm read-only tools work, denied permissions return forbidden, mutations request approval, and other server UUIDs stay inaccessible.

Upgrade

Upgrades preserve encrypted history, private ChatGPT state, and runtime data:

bash

ainx upgrade aiassistant.ainx

bash

blueprint -install aiassistant

Remove

Removal permanently deletes private Codex credentials, runtime state, workspaces, and stored assistant history. Export anything required first.

bash

ainx remove aiassistant