Zum Hauptinhalt springen

Quick start

Install the app-configurator, connect it to your instance, and run your first audit in a few minutes.

1. Mint a service token​

In the Backoffice, go to Admin → Service tokens and create one:

  • Scope config:read to audit and validate; add config:write to let the agent apply fixes.
  • Optionally narrow it to a single app, or set an expiry.

Copy the token (appilot_pat_...). It is shown once.

2. Install the skill​

Claude Code​

/plugin marketplace add appilot/appilot-plugins
/plugin install app-configurator@appilot

Claude asks for the endpoint, token, and optional app ID when it enables the plugin. The token is stored as a sensitive credential.

Codex​

codex plugin marketplace add /absolute/path/to/app-pilot
codex plugin add app-configurator@appilot

The Codex plugin installs both the skill and MCP server globally. Start a new task after installation.

Claude Desktop​

Build the bundle and open it. Desktop asks for the endpoint and token, and keeps the token in your operating system's keychain.

pnpm -C packages/tools/appilot-mcp build
pnpm -C packages/tools/appilot-mcp build:mcpb
open packages/tools/appilot-mcp/dist/appilot-configurator.mcpb

ChatGPT and claude.ai​

Neither can start a program on your machine, so both connect to a deployed Appilot MCP endpoint over HTTPS. If your team runs one, you need its URL and nothing else: the connection asks for your service token once, on a consent screen, and stores it for you.

  • ChatGPT: Settings, Apps, Advanced settings, turn on Developer mode, then add a connector for https://<your-mcp-host>/mcp using OAuth.
  • claude.ai: Settings, Connectors, Add custom connector, same URL.

Running the endpoint is an operator task, covered in MCP reference.

Cursor​

Copy skills/app-configurator to ~/.cursor/skills/app-configurator. Register the MCP server in ~/.cursor/mcp.json using the JSON from the next section.

Antigravity​

Copy skills/app-configurator to:

  • ~/.gemini/config/skills/app-configurator for Antigravity IDE.
  • ~/.gemini/antigravity-cli/skills/app-configurator for Antigravity CLI.

Register the MCP server in ~/.gemini/config/mcp_config.json.

3. Point it at your instance​

Set the connection in the MCP client's secure environment or credential store:

export APPILOT_BASE_URL="https://api.appilot.de"  # or your on-premise URL
export APPILOT_PAT="appilot_pat_..."
export APPILOT_APP_ID="123"                        # optional default app

Do not commit service tokens. When the client has no secret store, forward the variables from its parent environment instead of writing the token into a project file.

If you are not using a plugin, add the MCP server manually after the package is published:

{
  "mcpServers": {
    "appilot": {
      "command": "pnpm",
      "args": ["dlx", "@betterknow/appilot-mcp"]
    }
  }
}

Local or air-gapped (from a build, no npm)​

@betterknow/appilot-mcp is not on the registry yet, and a sovereign/air-gapped instance may have no registry access at all. In both cases, run the server from a local build. Build once:

pnpm -C packages/tools/appilot-mcp build   # emits dist/index.bundle.js

Then point the MCP entry at the self-contained bundle (node + an absolute path) instead of npx:

{
  "mcpServers": {
    "appilot": {
      "command": "node",
      "args": ["/absolute/path/to/appilot-mcp/dist/index.bundle.js"]
    }
  }
}

The server starts and advertises its tools even before the endpoint is configured. A live call returns a clear configuration error until APPILOT_BASE_URL is available.

The static gate (validate_config) needs no network; only the server echo and live soak reach your instance. This is the path to use for local testing before the package is published.

4. Run an audit​

Ask your agent:

Audit my Appilot app's configuration.

It will discover the instance, read the content model, validate against the health contract, and return a prioritized report. Then:

Fix the critical and high findings, show me the changes first.

With a config:write token it applies the edits (the server re-validates each one) and re-runs validation to confirm they are resolved.

5. Soak the live page (optional)​

To prove selectors resolve on the real page, provide an authenticated session and ask the agent to soak:

export APPILOT_SOAK_STORAGE_STATE="/path/to/session.json"  # Playwright storageState

Soak the control selectors for app 123 against https://myapp.example.com/tasks

This catches selectors that pass every static check but are gone on the next render.

Advisory mode (no MCP)​

No server configured? Paste or export your configuration and ask the agent to review it against the contract. It cannot write or soak, but it produces the same prioritized findings and the exact edits to make.