/aiq-deploy

name: aiq-deploy
description: |
  Use when asked to install, deploy, run, validate, troubleshoot, or stop NVIDIA AI-Q Blueprint infrastructure.
license: Apache-2.0
compatibility: |
  Designed for Claude Code, OpenCode, Codex, and Agent Skills-compatible tools. Requires Git, network
  access to GitHub, and one selected runtime path: Docker Compose v2 for the default local deployment,
  Python 3.11+ and uv for local process or CLI mode, Node.js 20+ and npm for local web UI mode, or
  kubectl 1.28+ and Helm 3.12+ for Kubernetes and Helm mode.
metadata:
  version: "2.1.0"
  author: "NVIDIA AI-Q Blueprint Team <aiq-blueprint@nvidia.com>"
  github-url: "https://github.com/NVIDIA-AI-Blueprints/aiq"
  tags:
    - nvidia
    - aiq
    - blueprint
    - deploy
    - operations
    - agent-skills
allowed-tools: Read Bash

AIQ Deploy Skill

Purpose

Use this skill to get a local or self-hosted NVIDIA AI-Q Blueprint server running and verified for use by `aiq-research`.

This skill owns setup, deployment, operational checks, troubleshooting, and shutdown. It does not run deep research itself. After deployment is healthy, hand off the verified server URL to `aiq-research`. The workflow stays explicit so deployment validation and handoff are repeatable across supported agent clients.

Prerequisites

Users need:

• Access to clone or update `https://github.com/NVIDIA-AI-Blueprints/aiq`.
• Git available in the shell.
• One deployment runtime:
• Docker Engine with Docker Compose v2 for the default durable local deployment.
• Python 3.11+ and `uv` for local process or CLI mode.
• Node.js 20+ and `npm` for local browser UI development mode.
• `kubectl` 1.28+, Helm 3.12+, and access to a Kubernetes cluster for Helm mode.
• Network access to GitHub, NVIDIA-hosted model endpoints, and any selected search provider.
• Credentials stored outside chat. Hosted-model usage requires `NVIDIA_API_KEY`; web research requires at least

one supported search provider key such as `TAVILY_API_KEY`, `SERPER_API_KEY`, or `EXA_API_KEY`.

• System capacity for the selected runtime. Docker Compose mode starts the AI-Q backend and PostgreSQL by default;

browser UI mode also uses frontend port `3000`. Self-hosted model or RAG deployments may require GPU resources.

Before writing secrets, verify `deploy/.env` is ignored:

git check-ignore deploy/.env

Expected output: `deploy/.env` or a matching ignore rule. If it is not ignored, stop and fix the ignore rule before placing credentials in the file.

Instructions

1. Locate or clone the AI-Q repository. 2. Confirm the expected repository files exist. 3. Select the deployment mode. 4. Prepare `deploy/.env` without overwriting user secrets. 5. Check runtime prerequisites for the selected path. 6. Start the selected deployment. 7. Run basic validation. 8. Report the verified `AIQ_SERVER_URL` for `aiq-research`. 9. Ask whether to run optional deep research completion validation.

Step 1 - Locate or clone AI-Q

If no AI-Q checkout exists, read `references/locate-or-clone.md` before cloning. In an existing checkout, confirm the required files:

pwd
test -f pyproject.toml
test -f deploy/.env.example
test -d configs

Expected output: `pwd` prints the AI-Q repository path; the `test` commands exit with status 0 and no output.

Step 2 - Select the deployment mode

If the user asks to install, deploy, set up, or run AI-Q without naming a mode, ask:

How do you want to run AI-Q?

1. Skill backend - backend-only service for aiq-research w/o browser UI.
2. CLI - interactive terminal AI-Q.
3. UI - browser AI-Q app with backend and frontend.
4. Custom - choose an existing AI-Q config or review advanced customization docs before deployment.

Wait for the user's answer before starting services.

Do not ask this question when the user already specified a mode, such as Docker Compose, Helm, UI, CLI, or Agent Skill backend. Do not ask the full mode question when `aiq-research` routed here because a deep research request needs a backend. In that case, prefer Agent Skill backend and ask only for permission to start it if needed.

Step 3 - Prepare environment and secrets

Read `references/env-and-secrets.md` before changing `deploy/.env`.

if [ ! -f deploy/.env ]; then
  cp deploy/.env.example deploy/.env
  echo "created deploy/.env from deploy/.env.example"
fi

Expected output when the file is missing: `created deploy/.env from deploy/.env.example`. Expected output when the file already exists: no output, and the existing file is preserved.

Never print secret values. If credentials are missing, ask the user to update `deploy/.env`; do not ask them to paste secret values into chat.

Step 4 - Route to the selected deployment path

Match the user request, then read the referenced file before acting:

| User Intent | Reference | |---|---| | No AI-Q checkout exists, install AIQ, clone AIQ, locate repo | `references/locate-or-clone.md` | | Configure environment, check API keys, inspect `.env` | `references/env-and-secrets.md` | | Choose an AI-Q workflow config, understand config files, set `BACKEND_CONFIG` or `CONFIG_FILE` | `references/configs.md` | | Backend-only local server for `aiq-research`, AIQ as an Agent Skill | `references/skill-backend.md` | | Terminal assistant, CLI-only run, no web UI | `references/terminal-cli.md` | | Quick local development run, start UI/backend without containers | `references/local-web.md` | | Default durable local deployment, Docker Compose, containers, PostgreSQL | `references/docker-compose.md` | | Kubernetes, Helm, cluster deployment | `references/kubernetes-helm.md` | | Foundational RAG / FRAG integration | `references/frag.md` | | Basic health checks, shallow smoke checks, handoff to `aiq-research` | `references/validation.md` | | Optional deep research completion validation | `references/end-to-end-validation.md` | | Logs, unhealthy services, port conflicts, config failures | `re