Aiq Deploy
OpenAIOfficialCreated by NVIDIA AI-Q Blueprint TeamDistributed by OpenAI
- Skill
- Workflow
- Cloud and DevOps
- Apache-2.0
- Medium risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The aiq-deploy skill provides a structured, repeatable workflow for installing and managing NVIDIA AI-Q Blueprint infrastructure. It handles the end-to-end process of environment setup, service deployment across various runtimes (Docker Compose, Kubernetes, CLI, or local process), and health verification. The skill is designed to prepare a stable, verified server instance for use by the aiq-research agent, ensuring that all prerequisites and configuration requirements are met before handoff.
What it does
- Clones or verifies the AI-Q repository structure.
- Guides the user through selecting a deployment mode (Docker, Helm, CLI, or local).
- Manages environment variable configuration and secret handling via deploy/.env.
- Executes deployment commands for the chosen runtime.
- Performs health checks and validates service readiness.
- Provides the verified server URL for downstream agent consumption.
When to use it
- When you need to set up a new instance of the NVIDIA AI-Q Blueprint.
- When you need to troubleshoot or restart an existing AI-Q deployment.
- When preparing an AI-Q backend server for use by the aiq-research agent.
- When you need to switch between different deployment modes like CLI, UI, or containerized backends.
Advantages
- Ensures consistent deployment outcomes through standardized validation steps.
- Supports multiple deployment runtimes including Docker Compose and Kubernetes.
- Maintains security by keeping credentials out of chat transcripts.
- Provides clear handoff procedures for integration with other AI agents.
Usage examples
- “Deploy the AI-Q backend using Docker Compose.”
- The agent will verify prerequisites, configure the environment, start the Docker containers, run health checks, and provide the AIQ_SERVER_URL.
- “I need to troubleshoot my AI-Q deployment, it is not responding.”
- The agent will check service status, inspect logs, verify port availability, and guide you through the troubleshooting reference.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/openai/aiq-deploy/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip aiq-deploy.zip -d .agents/skills
Documentation by NVIDIA AI-Q Blueprint Team
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
uvfor local process or CLI mode.Node.js 20+ and
npmfor local browser UI development mode.kubectl1.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 asTAVILY_API_KEY,SERPER_API_KEY, orEXA_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/.envExpected 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
Locate or clone the AI-Q repository.
Confirm the expected repository files exist.
Select the deployment mode.
Prepare
deploy/.envwithout overwriting user secrets.Check runtime prerequisites for the selected path.
Start the selected deployment.
Run basic validation.
Report the verified
AIQ_SERVER_URLforaiq-research.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 configsExpected 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"
fiExpected 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 | references/troubleshooting.md |
| Stop services, restart, rebuild, safe cleanup | references/shutdown.md |
Step 5 - Validate and hand off
After startup, read references/validation.md and run the appropriate checks for the selected mode. For the default
local backend, verify health:
curl -sf http://localhost:8000/healthExpected output: a successful JSON health response or an empty successful response depending on the server build. If the
command fails, read references/troubleshooting.md and diagnose before claiming the backend is ready.
aiq-research needs a reachable AI-Q server URL. If the backend is on the default port, no extra configuration is
needed:
AIQ_SERVER_URL=http://localhost:8000If the backend runs elsewhere, tell the user to set:
export AIQ_SERVER_URL="http://localhost:<PORT>"Do not continue into deep research or deep research completion validation unless the user asks for it or confirms the post-deploy validation prompt. This skill's success criterion is a deployed and basically validated server, not report generation quality.
Version Compatibility
IMPORTANT: This skill is designed for NVIDIA AI-Q Blueprint version 2.1.0.
Semantic Versioning Compatibility Rules:
Skill version: X.Y.Z
Blueprint version: A.B.C
Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)Examples:
Skill version 2.1.0 is compatible with Blueprint version 2.1.0.
Skill version 2.1.0 is compatible with Blueprint version 2.2.0.
Skill version 2.1.0 is compatible with Blueprint version 2.1.5.
Skill version 2.1.0 is not compatible with Blueprint version 3.0.0.
Skill version 2.1.0 is not compatible with Blueprint version 2.0.0.
If your Blueprint version is not compatible:
Check for an updated skill version matching your Blueprint version.
Use a Blueprint version compatible with this skill.
Proceed with caution only when the user accepts the compatibility risk; deployment commands or config names may have changed.
Security Best Practices
Never print secret values. Check only whether required environment variables are set.
Store credentials in
deploy/.envor environment variables, not in chat transcripts, shell history, committed files, or example commands.Do not overwrite
deploy/.envwhen it already exists.Ask before destructive cleanup such as deleting Docker volumes with
down -v.Do not claim FRAG is ready unless both
RAG_SERVER_URLandRAG_INGEST_URLare configured and reachable.Run verification commands yourself when possible.
Limitations
This skill prepares and validates AI-Q infrastructure; it does not judge deep research report quality.
It cannot provide or inspect secret values. Users must configure credentials outside chat.
Helm, FRAG, custom config, and self-hosted model paths depend on infrastructure the user controls.
Destructive cleanup, such as deleting Docker volumes, requires explicit user approval.
Examples
Example 1: Deploy a backend-only Skill server with Docker Compose
test -f deploy/.env || cp deploy/.env.example deploy/.env
git check-ignore deploy/.env
cd deploy/compose
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml config --quiet
BUILD_TARGET=release docker compose --env-file ../.env -f docker-compose.yaml up -d --build aiq-agent
curl -sf http://localhost:8000/healthExpected output:
deploy/.env
<docker compose starts aiq-agent and dependencies>
<health endpoint returns a successful response>If Docker, ports, credentials, or health checks fail, read references/troubleshooting.md before retrying.
Example 2: Hand off a non-default backend URL to aiq-research
export AIQ_SERVER_URL="http://localhost:8100"
curl -sf "$AIQ_SERVER_URL/health"Expected output: a successful health response. Then tell the user to keep AIQ_SERVER_URL set before invoking
aiq-research.
References
| Topic | Documentation |
|---|---|
| Locate or clone AI-Q | references/locate-or-clone.md |
| Environment and secrets | references/env-and-secrets.md |
| Workflow configs | references/configs.md |
| Agent Skill backend | references/skill-backend.md |
| CLI deployment | references/terminal-cli.md |
| Local web deployment | references/local-web.md |
| Docker Compose deployment | references/docker-compose.md |
| Kubernetes and Helm deployment | references/kubernetes-helm.md |
| FRAG integration | references/frag.md |
| Basic validation | references/validation.md |
| End-to-end validation | references/end-to-end-validation.md |
| Troubleshooting | references/troubleshooting.md |
| Shutdown and cleanup | references/shutdown.md |
Common Issues
Issue: Backend port is already in use
Symptoms:
Docker Compose fails to bind port
8000.curl -sf http://localhost:8000/healthreaches an unexpected service or fails.
Causes:
Another AI-Q backend or local development server is already running.
PORTindeploy/.envconflicts with an existing process.
Solutions:
Identify the process:
lsof -nP -iTCP:8000 -sTCP:LISTENEither stop the conflicting process with the user's approval or set a different port in
deploy/.env, such asPORT=8100.Restart the selected deployment path and verify:
curl -sf http://localhost:8100/health
Issue: Required credentials are missing
Symptoms:
Infrastructure starts, but model-backed chat or research requests fail.
Logs mention unauthorized, forbidden, invalid key, or missing provider configuration.
Causes:
NVIDIA_API_KEYis missing or empty.No supported search provider key is configured for web research.
Solutions:
Check presence without printing values by following
references/env-and-secrets.md.Ask the user to update
deploy/.env; do not ask them to paste secrets into chat.Rerun
references/validation.mdafter the user updates credentials.
Issue: Backend is healthy but not compatible with aiq-research
Symptoms:
/healthsucceeds, but/chator/v1/jobs/async/agentsfails.aiq-researchreports that async agents are unavailable.
Causes:
The selected config is CLI-only or does not expose the web/API backend expected by the skill.
BACKEND_CONFIGorCONFIG_FILEpoints at the wrong AI-Q config.
Solutions:
Read
references/configs.mdand confirm the selected config is API-enabled.For the default Skill backend, use
configs/config_web_default_llamaindex.yml.Restart the backend and rerun
references/validation.md.
Issue: Docker cleanup would remove useful state
Symptoms:
Troubleshooting suggests
docker compose down -v.The user may have local PostgreSQL job or checkpoint data they want to keep.
Causes:
down -vremoves Docker volumes.Rebuilds and restarts are often enough for config or image changes.
Solutions:
Prefer a normal restart from
references/shutdown.md.Ask for explicit approval before running volume deletion.
After cleanup, rerun deployment and validation from the selected route.
Files
- ATTRIBUTION.mdAdded by AutoGineer1017 B
- BENCHMARK.md4.1 KiB
- LICENSEAdded by AutoGineer10.0 KiB
- SKILL.md13.0 KiB
- agents/openai.yaml173 B
- evals/evals.json1.4 KiB
- references/configs.md3.5 KiB
- references/docker-compose.md3.5 KiB
- references/end-to-end-validation.md5.6 KiB
- references/env-and-secrets.md3.8 KiB
- references/frag.md1.6 KiB
- references/kubernetes-helm.md983 B
- references/local-web.md1.2 KiB
- references/locate-or-clone.md1.3 KiB
- references/shutdown.md2.2 KiB
- references/skill-backend.md1.4 KiB
- references/terminal-cli.md755 B
- references/troubleshooting.md1.2 KiB
- references/validation.md3.2 KiB
- skill-card.md4.0 KiB
- skill.oms.sig7.5 KiB
LICENSE
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Requirements and compatibility
Written for: OpenAI Codex, Claude Code, OpenCode
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Declares allowed tools, Needs network access, Needs an API key, Needs a command-line tool
The author says: 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.
Security
What our scanner noticed· Medium risk
- Large base64-encoded blobs
- Instructions that use the network
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- NVIDIA AI-Q Blueprint Team
- Publisher
- OpenAI (Official)
- Distributed by
- OpenAI
- Source
- openai/plugins · plugins/nvidia/skills/aiq-deploy · commit d420d13
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (written by AutoGineer)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by NVIDIA AI-Q Blueprint Team or OpenAI.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aiq-deploy.zip