Last updated on 16th April 2026

Using DeployHQ with AI Agents

DeployHQ welcomes AI coding agents. Whether you are building an agent, using one to manage your deployments, or integrating DeployHQ into an automated workflow, the platform provides everything agents need to sign up, configure projects, deploy code, and monitor infrastructure -- all without a browser.

Three Ways Agents Can Integrate

Integration Best for Get started
REST API Programmatic access, custom integrations, any language API Documentation and OpenAPI spec
CLI (dhq) Terminal workflows, CI/CD pipelines, scripting CLI Documentation and GitHub
MCP Server Conversational AI assistants (Claude, Cursor, etc.) MCP Server

The OpenAPI specification at https://api.deployhq.com/docs.json is machine-readable and can be loaded directly by agents for full API discovery. Interactive documentation is available at api.deployhq.com/docs.

Getting Started: Agent Signup

Agents can create DeployHQ accounts programmatically using the Signup API. This is the only unauthenticated endpoint -- no existing credentials are required.

POST https://deployhq.com/api/v1/signup

Example request

curl -X POST https://deployhq.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "secure-password-here",
    "client": "my-agent-v1"
  }'

What you get back

The response includes everything an agent needs to start working immediately:

  • api_key -- Use with the account email for HTTP Basic Authentication on all subsequent API calls
  • ssh_public_key -- Add this to your repository provider (GitHub, GitLab, Bitbucket) so DeployHQ can access your repositories
  • oauth_urls -- URLs to connect GitHub, GitLab, and Bitbucket accounts via OAuth
  • mcp_config -- Credentials for configuring the DeployHQ MCP Server (account, API key, email). See Using MCP for Conversational Deployment below for the full server configuration 
{
  "account": {
    "subdomain": "my-company",
    "url": "https://my-company.deployhq.com"
  },
  "api_key": "a1b2c3d4e5f6...",
  "ssh_public_key": {
    "public_key": "ssh-ed25519 AAAA...",
    "fingerprint": "SHA256:..."
  },
  "oauth_urls": {
    "github": "https://github.com/login/oauth/authorize?...",
    "gitlab": "https://gitlab.com/oauth/authorize?...",
    "bitbucket": "https://bitbucket.org/site/oauth2/authorize?..."
  },
  "mcp_config": {
    "account": "my-company",
    "api_key": "a1b2c3d4e5f6...",
    "email": "developer@example.com"
  }
}

The signup endpoint is rate-limited to 3 requests per IP per hour. See the Signup API reference for full parameter details and error codes.

Use Cases

End-to-End Project Setup

An agent can go from zero to a running deployment in a single session. Here is the full flow using the CLI:

# 1. Sign up for a new account
dhq signup --email developer@example.com --password "secure-password"

# 2. Create a project
dhq projects create --name "my-app" --zone default

# 3. Connect a repository
dhq repos create -p my-app \
  --url git@github.com:myorg/my-app.git \
  --branch main

# 4. Add a server
dhq servers create -p my-app \
  --name production \
  --protocol ssh \
  --hostname example.com \
  --username deploy \
  --path /var/www/my-app

# 5. Deploy and wait for completion
dhq deploy -p my-app --server production --wait --json

The same flow works via the REST API. Use the returned api_key from signup for authentication:

# Create a project
curl -u developer@example.com:YOUR_API_KEY \
  https://my-company.deployhq.com/projects.json \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"project": {"name": "my-app"}}'

CI/CD Pipeline Automation

Use environment variables for authentication in CI/CD pipelines -- no interactive login required:

export DEPLOYHQ_ACCOUNT=mycompany
export DEPLOYHQ_EMAIL=ci@example.com
export DEPLOYHQ_API_KEY=your-api-key

# Deploy the current commit and wait for result
dhq deploy -p my-app --server production --wait --json

# Check exit code for pass/fail
if [ $? -ne 0 ]; then
  dhq deployments logs $(dhq deployments list -p my-app --json | jq -r '.data.records[0].identifier') -p my-app
fi

See CI/CD Integration for complete GitHub Actions and GitLab CI examples.

Monitoring and Debugging Deployments

Agents can check deployment status and retrieve logs to diagnose failures:

# List recent deployments
dhq deployments list -p my-app --json

# Watch a deployment in real-time
dhq deployments watch DEPLOYMENT_ID -p my-app

# Get detailed logs for a failed deployment
dhq deployments logs DEPLOYMENT_ID -p my-app

Using the API directly:

# Get deployment status
curl -u email:api_key \
  https://account.deployhq.com/projects/my-app/deployments.json \
  -H "Accept: application/json"

# Get deployment log
curl -u email:api_key \
  https://account.deployhq.com/projects/my-app/deployments/DEPLOYMENT_UUID/log.json \
  -H "Accept: application/json"

Managing Configuration

Agents can manage environment variables, config files, build commands, and excluded files:

# Environment variables
dhq env-vars create -p my-app --name DATABASE_URL --value "postgres://..."
dhq env-vars create -p my-app --name RAILS_ENV --value production

# Config files
dhq config-files create -p my-app \
  --path config/database.yml \
  --body "production:\n  adapter: postgresql\n  database: myapp_prod"

# Build commands
dhq build-commands create -p my-app --command "npm install" --description "Install dependencies"
dhq build-commands create -p my-app --command "npm run build" --description "Build"

# Account-wide global variables (shared across all projects)
dhq global-env-vars create --name SHARED_API_KEY --value "..."

Using MCP for Conversational Deployment

AI assistants with MCP support can interact with DeployHQ using natural language. Configure the MCP server with the credentials returned from signup:

{
  "mcpServers": {
    "deployhq": {
      "command": "npx",
      "args": ["-y", "deployhq-mcp-server"],
      "env": {
        "DEPLOYHQ_EMAIL": "developer@example.com",
        "DEPLOYHQ_API_KEY": "your-api-key",
        "DEPLOYHQ_ACCOUNT": "my-company"
      }
    }
  }
}

Once configured, the AI assistant can respond to requests like:

  • "Deploy the latest changes to production for my-app"
  • "Why did the last deployment fail?"
  • "Show me the servers configured for my-app"
  • "Create a global environment variable called API_SECRET"

See the MCP Server documentation for the full list of available tools and configuration options.

Best Practices for Agents

  • Attribution: Always include the client parameter when using the Signup API (e.g., "client": "my-agent-v1"). This helps DeployHQ track agent-originated accounts and improve agent support.
  • JSON output: Use the --json flag with all CLI commands for machine-parseable output. The CLI writes structured data to stdout and human-readable messages to stderr.
  • Error handling: API error responses include error_code and hint fields for programmatic handling. See Handling Errors for the full list of error codes.
  • Rate limits: The signup endpoint allows 3 requests per IP per hour. Other API endpoints return Retry-After headers when rate-limited.
  • Email verification: New accounts require email verification before deployments can run. Build this into agent workflows by checking the email_verified field in the signup response.
  • Idempotency: Check if resources exist before creating them to avoid duplicates. Use dhq projects list --json or the API to verify before creating.
  • Security: Store API keys in environment variables or secure credential stores. Never hardcode credentials in scripts or commit them to repositories.

Local AI Assistant (dhq assist)

The CLI includes a built-in AI assistant powered by Ollama that runs entirely on your machine. This is best suited for developers who are not already using a coding agent like Claude Code, Codex, or Cursor. If you are already working inside one of those agents, the agent itself can use the CLI and API directly -- there is no need for a separate local assistant.

However, dhq assist is a good fit if:

  • You want complete privacy -- all data stays local, nothing is sent to external services
  • You prefer a lightweight, offline option that works without an internet connection (after initial setup)
  • You want quick deployment help without opening a full coding agent session 
# One-time setup (installs Ollama + downloads the model)
dhq assist --setup

# Ask about a deployment
dhq assist "why did my deploy fail?" -p my-app

# Interactive conversation
dhq assist --interactive -p my-app

See AI & Agents for full setup instructions, model options, and agent plugin configuration.

Agent Plugin Setup

The CLI includes a setup command to install agent integrations for popular AI coding tools:

dhq setup claude     # Claude Code / Claude Desktop
dhq setup codex      # OpenAI Codex
dhq setup cursor     # Cursor
dhq setup windsurf   # Windsurf

These commands configure the MCP server and credentials for each tool automatically. See AI & Agents for details.