AI Assistant and Agent Integration
The DeployHQ CLI includes a local AI assistant for deployment help and integrations for AI coding agents like Claude Code and OpenAI Codex.
AI Assistant (dhq assist)
Get AI-powered help for your deployments using a local LLM. All data stays on your machine -- nothing is sent to external AI services.
If you are already using an AI coding agent like Claude Code, Codex, or Cursor, your agent can interact with DeployHQ directly through the CLI and API -- you do not need dhq assist. The local assistant is best suited for developers who want a privacy-first, offline-capable option without relying on an external coding agent. It uses an open-source model via Ollama and keeps all data on your machine.
Setup
The assistant requires Ollama running locally. Run the one-time setup:
dhq assist --setup
This installs Ollama (if needed) and downloads the default model (qwen2.5:3b, approximately 2GB).
Asking Questions
# Ask about a deployment
dhq assist "why did my deploy fail?" -p my-app
# Get suggestions
dhq assist "what should I do?" -p my-app
# Ask about DeployHQ concepts
dhq assist "what does transfer_files do?"
# Print the answer in one piece instead of streaming it
dhq assist "why did my deploy fail?" -p my-app --no-stream
The assistant automatically gathers context from your project (recent deployments, server configuration, logs) to provide relevant answers.
Interactive Mode
For a conversational experience:
dhq assist --interactive -p my-app
Checking Status
Verify that Ollama is running and the model is available:
dhq assist --status
Using a Different Model
dhq assist "why did my deploy fail?" --model llama3.2
Installing the DeployHQ Skill for AI Agents
The CLI can install a DeployHQ "skill" into the AI coding agents on your machine so they can discover and drive dhq commands directly. Supported agents include Claude Code, Cursor, OpenAI Codex, and Windsurf.
Reading the Skill
# Print the skill (setup steps for AI agents), without installing anything
dhq skills show
# Print one of its reference documents, for example the one for dhq launch
dhq skills show launch
An agent can read the skill this way in the session it is working in. A skill installed with dhq skills install is only picked up when the agent starts a new session, so an agent that is setting DeployHQ up right now reads it with dhq skills show. The output is plain Markdown; add --json for {name, content, references}.
Listing Supported Agents
dhq skills list
This shows every supported AI agent and whether the DeployHQ skill is already installed.
Installing the Skill
# Install for all detected user-scope agents (Claude Code, Cursor, etc.)
dhq skills install
By default, this installs for the user-scope agents detected on your machine. Project-scope agents (such as GitHub Copilot) are skipped so that running the command never silently modifies the current repository.
To install for a specific agent -- including a project-scope one -- pass --agent:
# Install for a specific agent by name
dhq skills install --agent claude-code
# Install for a project-scope agent (writes into the current repository)
dhq skills install --agent copilot
dhq hello runs dhq skills install as part of guided onboarding, so in most cases you never need to run it separately. dhq --help tells AI agents to read the skill with dhq skills show, and so do the first messages an agent meets during setup (when nobody is signed in, or no project is set). They also give the command that installs it for future sessions for that agent only, for example dhq skills install --agent claude-code, rather than for every AI tool on the machine. dhq --help also points at https://www.deployhq.com/agents.md.
Deprecated: dhq setup
Earlier versions used dhq setup <agent> (for example dhq setup claude) to install per-agent plugins one at a time. That command still works but is deprecated -- prefer dhq skills install, which detects your installed agents automatically.
# Deprecated -- use "dhq skills install" instead
dhq setup claude
dhq setup codex
dhq setup cursor
dhq setup windsurf
Each dhq setup command installs for your user account by default (Cursor has no user-level install, so it always needs --project). Add --project to install into the current repository instead, or --uninstall to remove the installed files:
# Install the Claude Code skill into the current project only
dhq setup claude --project
# Remove a previously installed integration
dhq setup claude --uninstall
The equivalent of dhq setup <agent> is dhq skills install --agent <name>, for example dhq skills install --agent claude-code.
First-Time Setup Through an Agent
The installed skill guides an agent through first-time setup one small step at a time: it asks whether you already have a DeployHQ account, has you sign in or sign up in your own terminal, asks where you want to deploy, and asks before changing anything on your server or running the first deployment. It never needs your API key or passwords on a command line, so do not paste credentials into an AI chat. If the agent runs a command while you are not signed in, the CLI tells it to ask you to run dhq auth login, or dhq signup if you have no account yet, in a separate terminal window, and not through the agent's ! shortcut.
Command Catalog
The CLI exposes a full command catalog as JSON, designed for AI agent discovery:
dhq commands --json
This outputs every command, subcommand, flag, and description in a structured format that agents can parse to understand available operations.
Each command also carries two safety hints for automation:
requires_confirmationistruefor commands that change what runs on your servers, delete something, or create an account, for exampledeploy,rollback,launch,signup, and everydeletecommand. An agent should check with you before running these. Rundhq commands --jsonfor the full list.safe_for_automationmeans the command behaves deterministically in non-interactive mode and is fine to run without a person watching. It isfalsefor any command that is not explicitly marked safe, including commands that print secrets, such asauth token(which prints your API key).
Agent-Optimized Help
dhq --help --agent
This outputs help in JSON format optimized for machine consumption.
Agent Identification
When running the CLI from an automation agent, set the DEPLOYHQ_AGENT environment variable to identify the agent:
DEPLOYHQ_AGENT=my-bot dhq deploy -p my-app --json
The CLI also automatically detects common agent environments:
- DEPLOYHQ_AGENT environment variable
- CLAUDE_CODE or CLAUDECODE environment variable (Claude Code)
- CURSOR_AGENT environment variable (Cursor)
- WINDSURF_AGENT environment variable (Windsurf)
- Standard CI environment variables (GitHub Actions, GitLab CI, etc.)
MCP Server
DeployHQ provides a hosted MCP (Model Context Protocol) server at https://mcp.deployhq.com/mcp that lets AI assistants such as Claude read your accounts, projects, servers, and deployments. There is nothing to install: you sign in to DeployHQ from your assistant. The hosted server is read-only for now, so use the CLI for anything that changes a deployment.
Run dhq mcp to print the setup for your assistant:
dhq mcp
In a terminal this shows the claude mcp add --transport http ... command for Claude Code, along with an mcpServers JSON snippet for other clients. Add --json to get the same configuration as JSON:
dhq mcp --json
Local MCP Server
The earlier local server, which runs on your machine over stdio, is still available:
dhq mcp --local
MCP client configurations of the form {"command": "dhq", "args": ["mcp"]} continue to work: when the command receives piped input it starts the local server and warns that this behaviour is deprecated. Switch those clients to the hosted server, or add --local to the arguments if you want to keep the local one.
For detailed setup and usage instructions, see the MCP Server documentation.
Showing Resources by URL
Resolve a DeployHQ URL to structured data:
dhq show https://mycompany.deployhq.com/projects/my-app
This is useful for AI agents that encounter DeployHQ URLs in conversations or documents.