DEV Community: DeployHQ

Self-Host n8n on a VPS: Docker, HTTPS, and Git-Based Updates

DeployHQ — Thu, 21 May 2026 09:40:22 +0000

Most n8n self-hosting tutorials stop at docker compose up. That gets you a running instance, but it leaves a real gap: where do your workflows live? How do you upgrade without losing them? How do you roll back a bad change? Treat your n8n server like any other application — workflows in Git, infrastructure in Docker Compose, deploys triggered from main — and self-hosting becomes a maintainable habit instead of a fragile pet project.

This guide walks through standing up n8n on a single VPS with Docker, putting it behind HTTPS, and wiring it to a DeployHQ project so every change to your workflow repo updates the server. By the end you'll have a production-ready instance with backups, version control, and one-click rollback when something goes wrong.

What you'll build

n8n running in Docker on a single Ubuntu VPS
Postgres alongside it as the data store (not SQLite — more on that below)
Nginx + Let's Encrypt in front for HTTPS on your own domain
A Git repository that holds the docker-compose.yml, environment template, and an exportable JSON copy of every workflow
DeployHQ wiring the repo to the server, so a git push to main reconfigures the stack and re-imports workflows

By the end you'll be able to develop a workflow locally (or on a staging instance), export it, commit, push, and watch DeployHQ deploy the change with rollback available if it misbehaves.

Why self-host n8n at all?

n8n Cloud is good. So why bother with a VPS?

Cost predictability. A $5-10/month VPS handles thousands of runs per day. Cloud pricing scales by execution.
Data stays on your infrastructure. Webhooks, credentials, and execution logs never leave the box.
Custom nodes. You can npm install community nodes the cloud version doesn't ship.
No execution limits. Long-running flows that hit cloud step caps just run.

The trade-off is operational ownership — you patch the OS, renew the certificate, watch the disk. Most of that is one-time setup. The rest of this guide is the one-time setup, done properly.

Prerequisites

A VPS with Ubuntu 22.04 or 24.04 and SSH access — any of Hetzner, DigitalOcean, Vultr, Linode work fine
A domain you control with an A record pointing at the VPS IP
A DeployHQ account (free trial — sign-up link at the end)
A GitHub or GitLab repository
Docker installed locally for testing

Step 1: Provision the VPS

SSH in as root, install Docker, and set up a deploy user:

ssh root@your-vps-ip
curl -fsSL https://get.docker.com | sh

adduser deploy
usermod -aG docker deploy
mkdir -p /home/deploy/n8n
chown deploy:deploy /home/deploy/n8n

From your local machine, copy your SSH key to the deploy user:

ssh-copy-id deploy@your-vps-ip

Confirm passwordless login works:

ssh deploy@your-vps-ip "docker --version"

You should see the installed Docker version. That's the account DeployHQ will use.

Step 2: The n8n Docker Compose stack

In your local repo, create docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: n8nio/n8n:1.74.0 # pin to a specific tag — don't use :latest in prod
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "127.0.0.1:5678:5678" # localhost only — Nginx will proxy
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: ${POSTGRES_DB}
      DB_POSTGRESDB_USER: ${POSTGRES_USER}
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_HOST: ${N8N_HOST}
      N8N_PROTOCOL: https
      N8N_PORT: 5678
      WEBHOOK_URL: https://${N8N_HOST}/
      GENERIC_TIMEZONE: ${TIMEZONE:-Europe/London}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n
      - ./workflows:/workflows:ro

volumes:
  postgres_data:
  n8n_data:

Four things matter here:

Postgres, not SQLite. SQLite is fine for kicking the tires. For anything you care about, Postgres handles concurrent executions, backups, and growth without complaint.
N8N_ENCRYPTION_KEY is sacred. It encrypts the credentials n8n stores in the database. Change it and every credential breaks — you'll have to re-enter every API key, OAuth token, and SSH credential. Generate it once with openssl rand -hex 32, store it in DeployHQ as a config file, and never lose it.
WEBHOOK_URL must be your public HTTPS URL. n8n bakes this into the URLs it gives webhook senders. If it's wrong, Stripe / GitHub / Slack will hit a dead address.
Port 5678 is bound to 127.0.0.1. Don't expose n8n directly to the internet — put it behind Nginx with TLS. Anyone hitting port 5678 from outside gets nothing.

Create .env.example to commit to the repo (without secrets):

POSTGRES_USER=n8n
POSTGRES_PASSWORD=
POSTGRES_DB=n8n
N8N_HOST=workflows.yourdomain.com
N8N_ENCRYPTION_KEY=
TIMEZONE=Europe/London

The real .env lives in DeployHQ's server config — never in the repo.

Step 3: Put Nginx in front with Let's Encrypt

On the VPS, install Nginx and Certbot:

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Add a server block at /etc/nginx/sites-available/n8n:

server {
    server_name workflows.yourdomain.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 3600; # long-running executions
        proxy_send_timeout 3600;
    }

    listen 80;
}

Enable it and run Certbot:

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d workflows.yourdomain.com

The proxy_read_timeout 3600 is important. n8n executions can run for minutes when a workflow waits on an external API — without that, Nginx kills the connection and the run appears to fail.

Step 4: First run

Back on your local machine, commit the repo and push it to GitHub:

git init && git add . && git commit -m "Initial n8n stack"
git remote add origin git@github.com:you/n8n-stack.git
git push -u origin main

For the very first deploy, SSH into the VPS, copy the .env over (DeployHQ will manage it from here on), and bring the stack up manually:

ssh deploy@your-vps-ip
cd /home/deploy/n8n
# (DeployHQ will populate docker-compose.yml on first deploy — for now scp it manually)
docker compose up -d

Visit https://workflows.yourdomain.com, create the admin account, and you're live.

Step 5: Wire up Git-based deploys with DeployHQ

This is the part most n8n tutorials skip. In DeployHQ:

Create a new project and point it at your repo. DeployHQ supports deploying directly from a GitHub repo to your server without you wiring webhooks by hand.
Add the VPS as a server. Username deploy, port 22, deployment path /home/deploy/n8n. Use the SSH key you authorised in Step 1.
Add the .env as a config file. In the server's config-files section, create /home/deploy/n8n/.env and paste the real values (Postgres password, N8N_ENCRYPTION_KEY, N8N_HOST). DeployHQ writes this file before every deploy — your secrets stay out of Git.
Configure the deploy SSH command: bash cd /home/deploy/n8n && \ docker compose pull && \ docker compose up -d && \ docker compose exec -T n8n n8n import:workflow --input=/workflows/ --separateThis pulls any new n8n image version, recreates containers with the new Compose config, and re-imports every workflow JSON from the mounted /workflows directory.
Enable auto-deploy on push to main. Every merge now triggers a deploy.

Push a no-op change to trigger the first run. Watch the DeployHQ log — you'll see the repo transferred, the env file written, the SSH commands executed. The site shouldn't blink: docker compose up -d only recreates containers if something actually changed.

If a deploy ever breaks something, DeployHQ's one-click rollback restores the previous repo state and re-runs the deploy command — a single button, no manual Compose juggling.

Step 6: Workflows as code

This is the payoff for everything above. Instead of the workflow is whatever I last clicked in the UI, your repo becomes the source of truth.

The flow:

Develop locally or on a staging instance. A spare n8n container on your laptop works fine.
Export the workflow. In the n8n UI: open the workflow → menu → Download → save the JSON to workflows/your-workflow-name.json in your repo.
Commit and push. bash git add workflows/your-workflow-name.json git commit -m "Add: Slack-to-Sheets sync workflow" git push
DeployHQ deploys. The deploy command runs n8n import:workflow --input=/workflows/ --separate, which upserts the workflow into the database. Existing workflows with the same ID are updated; new ones are created.

A few practical notes:

One JSON file per workflow. The --separate flag tells n8n's importer to treat each file independently. Easier diffs in PRs.
Credentials are not in the JSON. n8n stores them encrypted in the database, referenced by ID. Set up credentials once in the UI; the workflow JSON just references them. This is why N8N_ENCRYPTION_KEY matters — drop it and the references become unusable.
The UI is now read-only in your head. Anyone making changes in production goes back to staging, exports, commits. Drift kills you otherwise.

The same Compose pattern works for sidecar services — drop a Python agent or a Postgres backup container into the same docker-compose.yml, and DeployHQ deploys all of it together.

Step 7: Upgrade n8n safely

n8n releases often. The temptation is to use n8nio/n8n:latest and let it ride. Don't.

With a pinned tag, upgrading becomes a one-line PR:

- image: n8nio/n8n:1.74.0
+ image: n8nio/n8n:1.78.0

Push, DeployHQ deploys, the new image is pulled, the container recreated. If anything misbehaves, hit rollback and the previous tag is back in seconds. You get a git history of every n8n version that has ever run in production — handy when a workflow stops working and you need to find what changed.

Two upgrade hygiene tips:

Read the changelog before bumping a major. n8n occasionally deprecates nodes or changes execution semantics.
Snapshot Postgres before a major. A docker compose exec postgres pg_dump ... to a file in a backup directory takes seconds and saves hours.

For deploys in general, DeployHQ runs zero downtime deployments by default — when you eventually move to a multi-server setup, the rollout pattern stays the same.

Step 8: Backups

Two things to back up:

The Postgres database. Everything important — workflows, credentials, execution history — lives here.

docker compose exec -T postgres \
  pg_dump -U n8n -d n8n --no-owner --clean \
  > backup-$(date +%F).sql

Drop a small script in your repo at scripts/backup.sh that runs this and uploads the file to S3 (or B2, or any object store). Cron it nightly on the VPS.

The n8n_data volume. Holds binary attachments and custom nodes. Tar it once a week to the same store:

docker run --rm -v n8n_n8n_data:/data -v $PWD:/backup alpine \
  tar czf /backup/n8n-data-$(date +%F).tar.gz -C /data .

The workflows themselves are already in Git, so you don't need to back those up — that's the whole point of the workflows-as-code pattern.

Where to go from here

The pillar above gets you a single-node, production-ready n8n instance with version control and rollback. From here:

Drop a custom AI service next to n8n. The same docker-compose.yml handles a sidecar Python or Node service — expose it at http://agent:8000 and have any n8n workflow hit it as a webhook. Same VPS, same deploy pipeline, no extra infrastructure.
Compare with other self-hosted agent platforms. If n8n's node-based model isn't the right fit, look at alternatives covered on the blog: Paperclip as a self-hosted agent orchestrator, OpenClaw as a self-hosted AI assistant with a Skills plugin system, and Hermes Agent for self-improving agents on a VPS.
Run agents inside CI/CD. For a different shape of the same problem — agents that act on your repository — see how AI agents fit into CI/CD pipelines from GitHub issue to production deploy.
Drive deploys from a terminal agent. If you want Claude Code, Cursor, or Codex to trigger n8n redeploys for you, the DeployHQ CLI exposes a deployment trigger your AI agent can call.

Ready to put n8n on infrastructure you control, with a Git-driven deploy pipeline behind it? Start a free DeployHQ trial and wire your first push-to-deploy n8n stack in under twenty minutes.

Questions? Email us at support@deployhq.com or find us on X at @deployhq.

DeployHQ CLI: Deploy From Your Terminal (or Let Your AI Agent Do It)

DeployHQ — Mon, 11 May 2026 13:56:25 +0000

If you have ever wished you could deploy without leaving your terminal — no browser tab, no dashboard click, no context switch — that is exactly what the new DeployHQ CLI is built for. It is a single Go binary, called dhq, that wraps the entire DeployHQ API. You install it once and you can trigger deployments, watch them in real time, tail logs, and roll back from the command line. And because the output is machine-readable by default, your AI coding assistant can do the same thing on your behalf.

This guide walks through installing the CLI, authenticating, running your first deployment, watching it live, tailing logs, and rolling back. Then we cover the part most teams care about in 2026: wiring dhq into Claude Code, Cursor, Codex, and Windsurf so an AI coding agent can drive your deployments end to end.

Why a Terminal-First Deployment Tool Matters

Deploy steps are the easiest place for an engineering workflow to break flow. You finish a fix, you push, the test suite passes — and then you alt-tab to a browser to click a button. With a CLI on your $PATH, that step collapses into a single command. With the same CLI exposed to your AI assistant, the deploy step disappears from your workflow entirely: the assistant proposes it, you approve, it ships.

That second use case — agent-driven deployment — is why DeployHQ rebuilt the CLI from scratch. The previous Ruby gem (gem install deployhq) is now deprecated. The new tool, dhq, follows a strict output contract designed for both humans and agents:

stdout is always data — a clean table for humans, JSON when piped or when --json is set
stderr is always human messages — progress, warnings, errors
No interactive prompts when all required flags are provided

If you have read our take on why CLIs are the cleanest integration surface for AI coding agents, this is what that argument looks like in practice for deployments.

Installing the DeployHQ CLI

dhq ships as a single binary for macOS, Linux, and Windows (amd64 and arm64). Pick the install method that matches your environment:

# macOS (Homebrew)
brew install deployhq/tap/dhq

# Linux or macOS (universal install script)
curl -fsSL https://deployhq.com/install/cli | sh

# Windows (Scoop)
scoop bucket add deployhq https://github.com/deployhq/scoop-bucket
scoop install dhq

# From source (Go)
go install github.com/deployhq/deployhq-cli/cmd/dhq@latest

After install, confirm the binary is on your $PATH:

dhq --version

Both dhq --version and dhq version work — use whichever fits your scripts.

Authenticating

dhq supports two authentication paths: an interactive login that stores credentials in your OS keyring (for everyday human use), and environment variables (for CI runners and AI agents).

For the interactive flow:

dhq auth login

You will be prompted for your account domain (e.g. my-account.deployhq.com), your email, and an API key from Settings → Security. You can create or revoke API keys from the DeployHQ API settings page.

For non-interactive environments — CI runners, Docker images, AI agent sandboxes — set three environment variables instead:

export DEPLOYHQ_ACCOUNT="my-account"
export DEPLOYHQ_EMAIL="you@example.com"
export DEPLOYHQ_API_KEY="..."

This is the same pattern we recommend when pointing AI agents at CI/CD pipelines: credentials live in the runner's secret store, never in prompts or repo files.

Your First Deployment

The five commands you will reach for most often:

Command	What it does
`dhq projects list`	List projects on your account
`dhq servers list -p <project>`	List servers and groups for a project
`dhq deploy -p <project> -s <server>`	Trigger a deployment with live progress
`dhq deployments watch -p <project>`	Stream live progress for a deployment already running
`dhq deployments logs <id> -p <project>`	Fetch logs for a specific deployment
`dhq rollback <id> -p <project>`	Revert a previous deployment

A typical session looks like this. Discover what you have access to:

$ dhq projects list
NAME PERMALINK REPO
api-service api-service github.com/acme/api
marketing-site marketing-site github.com/acme/marketing

$ dhq servers list -p api-service
NAME IDENTIFIER TYPE BRANCH PATH
production prod-srv-01 SSH main /var/www/api
staging stage-srv-01 SSH main /var/www/api-staging

Then deploy. With --wait, you get a live TUI progress bar that updates as the deployment runs through its phases (fetch repo → build → upload → run SSH commands):

$ dhq deploy -p api-service -s staging --wait

When the deployment is done, the CLI exits with status 0 on success and non-zero on failure — exactly what your shell scripts and CI runners need.

Watching, Logs, and Rollback

Three operations turn the CLI from a fire and forget trigger into a control plane you can run from one terminal window.

Watch a deployment live. If a deploy is already in flight, attach to it from anywhere:

dhq deployments watch -p api-service

The watch view streams the same TUI you would see from --wait, but for a deployment that started elsewhere — useful when a teammate or a CI job kicked it off and you want to monitor without refreshing the dashboard.

Tail logs after the fact. When something fails, you want the full log without scrolling through the web UI:

dhq deployments logs DEP-12345 -p api-service

For agent-friendly output, add --json and pipe into jq:

dhq deployments logs DEP-12345 -p api-service --json | jq '.data.entries[] | select(.level=="error")'

Roll back a bad deploy. If a release goes sideways, revert to the previous successful deployment:

dhq rollback DEP-12345 -p api-service --wait

Rollback uses the same diff engine as a forward deploy, so the only files that move are the ones that changed. This is the same one-click rollback primitive exposed in the web UI, just from your terminal.

Output Contract: Why It Matters for AI Agents

Most CLIs were not designed to be called by AI coding agents. They mix progress messages with data on stdout, throw interactive prompts when you forget a flag, and return unstructured text that the agent has to guess how to parse.

dhq was built around three rules that fix that:

stdout is data, stderr is text — a piped command always returns parseable output; status messages never pollute it
JSON on demand, JSON when piped — dhq deploy ... --json returns machine-readable output, and the same auto-switches when stdout is a pipe
Breadcrumbs in every JSON response — the CLI tells the agent what to do next

A typical JSON response includes a breadcrumbs array that explicitly lists the next reasonable command:

{
  "ok": true,
  "data": { "deployment_id": "DEP-12345", "status": "completed" },
  "summary": "Deployment DEP-12345 to staging completed in 47s",
  "breadcrumbs": [
    {"action": "logs", "cmd": "dhq deployments logs DEP-12345 -p api-service"},
    {"action": "rollback", "cmd": "dhq rollback DEP-12345 -p api-service"}
  ]
}

The agent does not have to memorise the command surface. It runs one command, reads the breadcrumbs, and knows what to chain next. On failure the envelope flips — {ok: false, error, recovery} — so the agent gets the same structured handle on what went wrong and what to try next.

Wiring `dhq` Into Your AI Coding Assistant

This is where the real workflow change happens. With dhq on $PATH and the right rules file in your repo, your AI editor can deploy your code without you ever opening a browser. A full companion guide on driving DeployHQ from Cursor, Claude Code, and Windsurf is in the works (sister post coming Week 7) — what follows is the short version.

The pattern is the same across all four editors below: the capability lives in the editor's permissions config; the judgement lives in a behavioural rules file. Read-only commands (projects list, servers list, deployments logs, deployments watch) are safe by default. Destructive ones (deploy, rollback) should require an explicit human approval gate.

Claude Code

Claude Code governs shell access through .claude/settings.json. Allow the read-only dhq commands; require approval for the destructive ones:

{
  "permissions": {
    "allow": [
      "Bash(dhq projects:*)",
      "Bash(dhq servers list:*)",
      "Bash(dhq deployments logs:*)",
      "Bash(dhq deployments watch:*)"
    ],
    "ask": [
      "Bash(dhq deploy:*)",
      "Bash(dhq rollback:*)"
    ]
  }
}

Then drop a CLAUDE.md block at the project root telling Claude when to reach for the CLI. Behavioural rules belong in CLAUDE.md; we cover the full pattern in our guide to CLAUDE.md, AGENTS.md and Copilot Instructions:

## Deployment

This project uses DeployHQ. Use the `dhq` CLI for all deploys.

- After the test suite passes on a branch, propose `dhq deploy -p <project> -s staging --wait` and wait for my approval.
- Never run `dhq deploy ... -s production` without an explicit instruction containing the word "production".
- For a failing deploy, fetch logs with `dhq deployments logs <id>` before suggesting a fix.
- For a regression in production, propose `dhq rollback <id>` first, then debug.

Cursor

Cursor's Composer agent shells out the same way. Drop the rules in .cursor/rules/deployhq.mdc — that is the path current Cursor versions auto-load, with .mdc frontmatter:

We deploy with DeployHQ via the `dhq` CLI.

When asked to deploy:
1. Confirm the target environment in your message before running the command.
2. Use `dhq deploy -p <project> -s staging --wait` for staging.
3. For production, ask me to confirm in the chat before issuing the command.
4. After triggering, check `dhq deployments watch` until completion or failure.
5. On failure, run `dhq deployments logs <id>` and summarise the error before suggesting a fix.

Codex CLI / Windsurf

OpenAI's Codex CLI and Windsurf's Cascade agent both run shell commands natively. Once dhq is on $PATH they can call it without extra config — the work is in giving them the right behavioural rules so they do not deploy the moment they feel confident. We compared the three terminal agents in detail in Claude Code vs Codex CLI vs Gemini CLI, and the deployment pattern that emerged is the same: read commands open, write commands gated by an explicit instruction.

For an even shorter setup, dhq setup writes the right files for each editor in the right place — no manual config copying:

dhq setup claude # writes ~/.claude/skills/deployhq/SKILL.md
dhq setup cursor # writes .cursor/rules/deployhq.mdc in the current repo
dhq setup codex # writes AGENTS.md in the current repo
dhq setup windsurf # writes global_rules.md

Each variant installs a behavioural rules file the editor actually auto-loads, plus a SKILL.md decision tree and reference docs that teach the agent when each dhq command is appropriate. More on the design choices behind that in our piece on the developer CLIs that AI coding agents actually use well.

Using `dhq` in CI/CD

The same output contract that makes the CLI work for AI agents makes it trivial to drop into CI. A minimal GitHub Actions step:

env:
  DEPLOYHQ_ACCOUNT: ${{ secrets.DEPLOYHQ_ACCOUNT }}
  DEPLOYHQ_EMAIL: ${{ secrets.DEPLOYHQ_EMAIL }}
  DEPLOYHQ_API_KEY: ${{ secrets.DEPLOYHQ_API_KEY }}

steps:
  - name: Install dhq
    run: curl -fsSL https://deployhq.com/install/cli | sh

  - name: Deploy to staging
    run: dhq deploy -p api-service -s staging --wait --json

Auth via env vars, JSON output for machine parsing, exit code drives the build status. If the deploy fails, the CI job fails — no extra plumbing required. For more on running AI agents inside the same kind of pipeline, see our piece on agentic workflows in CI/CD.

Migrating From the Old Ruby Gem

If you have the old gem install deployhq tool installed, the migration is straightforward:

Install dhq using one of the methods above.
Run dhq auth login (or set the DEPLOYHQ_* environment variables) — your existing API keys still work.
Update any scripts that called deployhq deploy to dhq deploy -p <project> -s <server>.
Once everything is working, gem uninstall deployhq to remove the old tool.

The old Deployfile JSON format is no longer required — dhq reads project context from flags, environment variables, or your interactive auth state. This is a breaking change, but a small one: most users had a single Deployfile per repo, and the new flags are easier to drop into Makefiles, scripts, and CI configs.

Where to Go Next

The CLI is one piece of a larger story. DeployHQ is increasingly designed for both humans and agents — the DeployHQ agents page walks through how the platform thinks about tool design for AI editors, and where we are heading next.

If you do not have a DeployHQ account yet, start a free trial — install dhq, point it at your first project, and you can run an automated deployment from your terminal inside ten minutes.

Questions, edge cases, or feedback on the CLI? We would love to hear from you — drop us a line at support@deployhq.com or find us on @deployhq.

New DeployHQ integrations: Linear, Google Chat, Telegram, and signed webhooks

DeployHQ — Fri, 08 May 2026 13:35:35 +0000

We've spent the last few weeks closing the gap between the deploy finished and the right people know it finished. That gap is where production incidents hide: someone shipped a hotfix at 4pm, the chat channel was muted, the PR reviewer assumed it was still in staging, and the customer-facing status page never updated.

Five new integrations are now live, each filling a different version of that gap. One pushes status back into the place where engineers already review code. Three send alerts into the chat tools your team actually watches. The last one is a signed webhook for everything else — status pages, dashboards, CRMs, audit logs.

Deploy status, posted back to GitHub, GitLab, and Bitbucket

The new deployment notifications integration closes the most common visibility gap of all: a pull request shows the diff, the conversation, and the test results — but says nothing about whether the merge actually shipped, where it shipped to, or when. We covered why that gap matters in a comparison of how developers track pull requests, and the same logic applies after merge: reviewers shouldn't have to guess what happened to their code.

Once enabled, every DeployHQ deploy reports back to the originating Git provider. On GitHub, deploys appear under the Deployments tab and as commit statuses on PRs. On GitLab, they show up in the Environments view and on the merge request widget. On Bitbucket, they populate the native Deployments panel. You can map projects to environments — production, staging, QA, preview — so reviewers can see which commit landed where without leaving the code review.

There's no separate auth dance: the integration reuses the repository connection you already configured, and the audit trail of every deploy lives where the rest of your code history lives.

A Linear Release for every deploy, automatically

Release tracking is one of those tasks that sits between engineering and product, gets assigned to nobody, and quietly atrophies. The Linear integration takes it off the backlog: every time DeployHQ finishes a deploy, a Linear Release lands in your chosen pipeline — already linked to the issues that shipped, based on the issue IDs in the commit messages between this deploy and the last one.

The integration takes a single Linear API key and lets you route different environments to different release pipelines. Production deploys can populate your customer-visible release pipeline; staging deploys can populate an internal one. The integration only creates Releases — it doesn't move issues between states, so it composes cleanly with whatever workflow automation you already have. If you've thought about the difference between continuous delivery and continuous deployment, this is the seam where the two meet — automatic Releases let you keep continuous-delivery discipline without manual bookkeeping.

Card-formatted alerts in Google Chat spaces

For teams running on Google Workspace, the Google Chat integration drops deploy notifications straight into your existing spaces as native cards. Project name, branch, environment, deployer, and status are all visible at a glance — no plain-text wall.

Different projects can route to different spaces, or one project can broadcast to several. Useful pattern: send infra deploys to a quiet deploys-firehose space and customer-facing app deploys to your main engineering space, so the noise lives somewhere you can mute and the signal stays where people are paying attention. This is the same pattern we recommended when we enhanced our Slack notifications, now extended to Google Workspace teams.

Telegram alerts for the on-call rotation

Slack and Discord aren't the right fit for everyone. International teams, contractor pools, and on-call rotations often live in Telegram, where notifications hit personal devices reliably without a paid seat or a workspace invite. (For teams already on Discord or Microsoft Teams, we have a separate guide for routing deployment notifications there.)

The new integration uses the Telegram Bot API to push deploy alerts to any chat, group, or channel. Setup is three steps: create a bot through @botfather, add it to your destination, and paste the token plus chat ID into DeployHQ. There's no Telegram-side server to host — the bot infrastructure is Telegram's. A common deployment pattern: a private channel for production alerts that on-call engineers subscribe to, plus a group chat for the broader team.

Signed HTTP webhooks for everything else

Pre-built integrations cover the common destinations, but there's always a long tail: a customer-facing status page, an internal compliance log, a CRM that needs to know when a customer's tenant deployed, a custom dashboard the platform team built last quarter. The HTTP webhook integration handles those.

Every deploy event — start, success, failure — fires a signed POST to whatever URL you configure. Each request includes an X-DeployHQ-Signature header containing an HMAC-SHA256 of the raw body, keyed by your shared secret, so the receiving service can verify the request actually came from DeployHQ and wasn't replayed or forged. That matters as soon as the receiving endpoint is publicly reachable, which most webhook endpoints are.

If you'd rather poll than receive, the same data is available through the DeployHQ API for scripted deployment workflows. Common destinations we've seen people wire up: Statuspage and Atlassian Status, Datadog events, internal Postgres audit tables, ServiceNow tickets, custom Slack apps with richer formatting than the stock connector, and customer-success tools that surface deploy timing during support conversations.

Where this fits

Each of these reuses your existing DeployHQ project configuration — the same Git deployment automation you already have running picks up the new notification target on its next run. Multiple integrations can run in parallel: a single deploy can post a commit status to GitHub, create a Linear Release, drop a card into Google Chat, ping a Telegram channel, and fire a webhook to your status page.

For a wider tour of what plugs into DeployHQ — error trackers, monitoring tools, project management — the DeployHQ integrations roundup covers the broader picture, and the integrations index lists every pre-built connector. If your destination isn't there, the signed webhook covers it.

If you're not deploying with DeployHQ yet, start a free trial and wire up your first integration in the dashboard — most teams have deploy notifications flowing inside ten minutes.

Got questions or a destination you'd like us to integrate with natively? Reach us at support@deployhq.com or @deployhq on X.

Deploy Hermes Agent on a VPS: DeployHQ Workflow + How It Differs from OpenClaw

DeployHQ — Wed, 06 May 2026 14:27:19 +0000

If you read our OpenClaw VPS deployment guide and walked away with a thin self-hosted gateway between your messaging apps and an LLM, you got exactly what OpenClaw is designed to be. Hermes Agent — Nous Research's open-source agent that hit v0.12 last week — sits in adjacent territory but answers a different question. Where OpenClaw asks how do I route messages to a model?, Hermes asks how do I run an agent that gets better at its job over time?

For agencies, that distinction matters. One Hermes instance per client, deployed to a small VPS, can accumulate skills, remember context across sessions, and handle scheduled work without you babysitting it. It fits squarely into the broader pattern we've been writing about — autonomous AI agents reshaping deployment workflows — except the agent lives on infrastructure you control rather than a third-party SaaS. The catch: you need a way to keep the configuration, persona files, and skill bundles in sync across however many client servers you run. That's where DeployHQ comes in. This post covers what Hermes Agent actually is, how it differs from OpenClaw, and how to deploy it on a VPS with a repeatable Git-driven workflow.

What Hermes Agent does

Hermes Agent is a Python project under MIT license that runs as a long-lived process on whatever infrastructure you give it. The architecture has three pieces worth understanding before you deploy it:

A skills system that grows. Skills are procedural memory the agent writes for itself. When Hermes solves a task — say, generating a weekly client report from your analytics — it can save that workflow as a skill and refine it on future runs. Skills are portable JSON-and-prompt artifacts you can share between agents via the agentskills.io hub, which means an agency running ten Hermes instances can develop a skill once and propagate it to every client. If you've already worked with OpenClaw's skills system, the conceptual model is similar — Hermes just adds the autonomous self-curation layer on top.

Persistent cross-session memory. Hermes uses the Honcho framework for user modeling and LLM-summarized recall. Conversations from yesterday inform how it responds today. The agent also performs periodic memory nudges — compacting and reorganizing what it knows so the context window doesn't bloat indefinitely. None of this works without a persistent volume on disk; we'll come back to that.

Multi-channel messaging from one process. Out of the box: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, and SMS, plus a TUI for direct terminal interaction. The agent runs once and exposes itself everywhere.

On top of these, Hermes is model-agnostic — Nous Portal, OpenRouter (200+ models), OpenAI, NVIDIA NIM, or any custom endpoint — and supports six terminal backends including Docker, SSH, Daytona, and Modal for distributed or serverless execution. A SOUL.md file in the repo defines the agent's personality and operating constraints, which is the file you'll customize per client.

Hermes Agent vs OpenClaw: when to pick which

Both projects target the same broad audience (developers who want a self-hosted alternative to ChatGPT subscriptions) but the runtime profile is genuinely different.

	OpenClaw	Hermes Agent
Language	Node.js	Python
Process model	Single Node process	Containerised app + sidecar services
State	Stateless gateway	Persistent skills + memory
Min recommended VPS	2GB / 1 vCPU	8GB / 2 vCPU
Built-in tools	None — bring your own	40+
Scheduled tasks	External (cron)	Built-in scheduler
Multi-channel	Yes	Yes (15+ channels)
Best for	Thin chatbot front, BYO intelligence	Autonomous agents that learn

The trade-off lines up neatly. OpenClaw is leaner — a 4GB VPS comfortably runs OpenClaw alongside other services, and you keep your model logic, memory, and tooling in your own application code. Hermes is heavier — Docker-friendly, with more state to persist and back up, but you get the learning loop, scheduler, and tool catalogue without writing them yourself.

For most agency scenarios — I want to give each client a smart assistant that learns their business — Hermes wins. For projects where the agent is one component in a larger application you're already building, OpenClaw stays out of the way. If you've already deployed OpenClaw and want to keep it, Hermes can run alongside on the same VPS provided you have the RAM headroom. And if your real need is a chat front-end for self-hosted models rather than an autonomous agent, our LibreChat and Ollama VPS deploy guide covers a third path that doesn't pretend to be either.

Pre-flight checklist

Before touching the server:

A VPS with Ubuntu 22.04 LTS or Debian 12 , 8GB RAM , 2 vCPU , and at least 20GB SSD. Hetzner CPX21, DigitalOcean's $24 droplet, or equivalent.
A domain name pointed at the VPS (Hermes itself doesn't need HTTPS, but messaging webhooks for Telegram and Slack do).
An API key for at least one model provider. OpenRouter is the most flexible because you can swap models without redeploying.
A Git repository (GitHub, GitLab, or Bitbucket) for your Hermes configuration. Don't put .env files with real secrets in the repo — we'll handle those via DeployHQ environment variables.
A DeployHQ account. If you don't have one, sign up — the free tier covers a single project and is enough to follow along.

Step 1 — Server hardening

SSH in as root, create a non-root user, and lock the basics down:

adduser hermes
usermod -aG sudo hermes
ufw allow 22/tcp
ufw allow 443/tcp
ufw enable

Disable root SSH login and password auth in /etc/ssh/sshd_config, then reload. None of this is Hermes-specific — it's the baseline you should run on any server.

Step 2 — Install Docker

Hermes ships a docker-compose.yml and that's the path we recommend for production. We've covered the Docker container deployment pattern with DeployHQ in more depth before — the same pipeline applies here. Install Docker Engine and the Compose plugin from the official Docker repo (don't use Ubuntu's bundled docker.io package — it lags behind):

curl -fsSL https://get.docker.com | sh
usermod -aG docker hermes

Log out and back in as hermes so the group change takes effect. Verify with docker compose version.

Step 3 — Initial Hermes Agent install

Clone the repo and prepare the configuration:

cd /home/hermes
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
cp .env.example .env
cp cli-config.yaml.example cli-config.yaml

Edit .env with your model provider key and any messaging tokens (Telegram bot token, Slack signing secret, etc.). Edit SOUL.md to define the agent's persona — for an agency client this might be You are a senior project manager for ClientName. You answer questions about their deployments, surface blocked items from the standup channel, and never speculate when you don't have data.

Bring it up:

docker compose up -d
docker compose logs -f

Watch the logs until you see the agent connect to your messaging channels. From here, the agent is alive — but every config change still requires SSH, which is exactly the operational footgun DeployHQ removes.

Step 4 — Move configuration into Git

Create a Git repo with this structure:

hermes-config/
├── SOUL.md
├── cli-config.yaml
├── skills/
│ ├── weekly-report.json
│ └── deploy-status-check.json
├── docker-compose.override.yml
└── deploy.sh

Note what's not in there: .env. Secrets stay in DeployHQ as environment variables and get written to disk during deploy. The docker-compose.override.yml lets you set production-specific values (volumes, restart policies, resource limits) without touching the upstream docker-compose.yml.

Push this to GitHub or GitLab. This is the repo DeployHQ will track.

Step 5 — DeployHQ project setup

In DeployHQ, create a new project and connect it to your config repo via GitHub or GitLab. Add your VPS as a server with the hermes user and SSH key.

Set the deployment path to /home/hermes/hermes-config. Add your secrets as DeployHQ environment variables — DeployHQ will write them as a .env file at deploy time:

In Build Pipeline (or as a deploy command), add:

cat > .env <<EOF
OPENROUTER_API_KEY=$OPENROUTER_API_KEY
TELEGRAM_BOT_TOKEN=$TELEGRAM_BOT_TOKEN
SLACK_SIGNING_SECRET=$SLACK_SIGNING_SECRET
EOF

Then add a post-deployment SSH command that copies the config into place and restarts the container:

cd /home/hermes/hermes-config
cp SOUL.md cli-config.yaml /home/hermes/hermes-agent/
cp -r skills/ /home/hermes/hermes-agent/
cd /home/hermes/hermes-agent
docker compose pull
docker compose up -d --remove-orphans

Wire up the auto-deploy webhook from your Git host. Now git push triggers a deploy: DeployHQ writes the latest config, pulls any updated container image, and restarts Hermes — no SSH session required. This is the build pipeline pattern that makes the whole thing reproducible.

Step 6 — Persistent data (this is the one most people miss)

Hermes' learning is worthless if it doesn't survive a container restart. In your docker-compose.override.yml:

services:
  hermes:
    volumes:
      - ./data:/app/data
      - ./memory:/app/memory
      - ./skills:/app/skills
    restart: unless-stopped

Back the data/ and memory/ directories up daily. restic to a Backblaze B2 bucket is the cheapest reliable option — about $0.005/GB/month. If your agent has been running for six months and you lose its memory, you've lost six months of accumulated context, which for a client-facing agent is genuinely painful.

The agency multi-tenant pattern

Here's where this stops being a single-server tutorial and starts paying for itself.

For an agency running Hermes for ten clients, you don't want ten copies of the same docker-compose.yml drifting apart. The pattern:

One Git repo per client — different SOUL.md, different model provider keys, different skills loadout.
One DeployHQ project per VPS — each pointed at its client's config repo.
One shared skills/ Git submodule — common skills (calendar lookup, time-tracking exports, deployment status) developed once, pulled into every client's repo.

When you build a new skill for one client and it generalises, push it to the shared submodule, bump the submodule pointer in the other clients' repos, and DeployHQ rolls it out everywhere. No SSH-and-rsync rituals; no risk of one server lagging six months behind. This is the same operational pattern we documented for self-hosting Vaultwarden across client VPS infrastructure — once you have it dialled in for one self-hosted service, every additional service plugs into the same pipeline. It's also why agencies tend to prefer DeployHQ over hand-rolled CI scripts when they get past three or four servers — the for agencies plan exists for exactly this kind of fan-out.

Common gotchas

Memory directory not mounted as a volume — every container restart wipes the agent's memory. Test by killing the container deliberately and confirming sessions persist.
Forgetting SOUL.md — Hermes will run with a generic persona, which is fine for testing but not what you want for a client deployment.
Free tier model rate limits — burst usage hits caps fast. OpenRouter's pay-as-you-go is the safety net.
WhatsApp/Signal bridges aren't built in — they require separate bridge processes. The Telegram and Discord integrations are the easiest starting points.
.env accidentally committed — use a pre-commit hook or DeployHQ's environment variables exclusively. Rotate any key that touched a public repo.

Where to go next

Hermes Agent is a heavier commitment than OpenClaw, but the autonomous skill curation and persistent memory are real differentiators if you want an agent that gets more useful over time rather than starting from zero on every conversation. For agencies running multiple clients, the Git-driven config pattern through DeployHQ is what makes ten Hermes instances tractable instead of ten independent operational headaches.

Start with one client repo before fanning out, watch how the agent's skills evolve over the first month, and only then start replicating the pattern across the rest of your client base. The Git-driven config workflow scales linearly; the operational complexity doesn't.

Got questions? Reach us at support@deployhq.com or on Twitter at @deployhq.

6 free GitHub repos that cut your Claude Code token bill

DeployHQ — Mon, 04 May 2026 05:56:24 +0000

If you use Claude Code seriously, your token budget is the new bottleneck. A long session blows past the context window, an unfiltered npm install dumps 4,000 lines into Claude's view, and the Max plan suddenly feels less generous. The good news: the open-source community has been quietly shipping repos that solve exactly this — compressing terminal output before it reaches the model, building knowledge graphs so Claude reads only what matters, and giving you a real-time view of where your tokens go.

Here are six free GitHub repos worth installing this week. Four of them cut your bill directly. Two help you see where the money is going so you can act on it. For a Max-plan user pushing daily, the combined effect can save $100+ a month. For a Pro user, you mostly get longer sessions and faster context — still worth the install.

Cut your token bill

1. rtk — compress terminal output before it hits Claude

rtk is a Rust CLI proxy that filters and compresses command output before it ever reaches your AI assistant's context. A git status shrinks from 119 characters to 28. A cargo test collapses from 155 lines to 3. An npm install drops from 4,000 lines to about 15. Across common dev commands, the maintainers report 60-90% token reduction.

The trick is straightforward: instead of running git status directly, Claude runs rtk git status, and only the meaningful diff hits the context window. A Claude Code hook can rewrite Bash commands transparently, so you don't have to retrain your muscle memory.

# macOS / Linux
brew install rtk

# Or with cargo
cargo install --git https://github.com/rtk-ai/rtk

Single Rust binary, zero dependencies, MIT licensed. If you only install one tool from this list, install this one.

2. caveman — make Claude talk like a caveman

caveman is a Claude Code skill that rewrites the model's own output to be terse. The spec is exactly what it sounds like: respond like a smart caveman. Cut articles, pleasantries, and filler. Keep all technical substance. Code blocks remain unchanged. Error messages stay quoted exactly. Technical terms stay intact.

The result reads weird at first — fix bug, line 42, null check missing, add if user — but it cuts roughly 75% of output tokens, and once you adjust, you stop noticing. The skill detects 30+ agents, including Claude Code, Codex, Cursor, Windsurf, Cline, and Aider.

# Claude Code (recommended)
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

# Universal fallback
npx skills add JuliusBrussee/caveman

If verbose Claude prose is what's chewing through your daily limit, this is the fastest fix on the list.

3. code-review-graph — let Claude read only what matters

code-review-graph tackles a different problem: when Claude has to review a PR or work in a large codebase, it ends up reading half the repo to understand the call graph. This tool parses your repository into an AST with Tree-sitter, stores it as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), and at review time computes the minimal set of files Claude actually needs to read.

The published benchmarks show 6.8× fewer tokens on code reviews and up to 49× reduction on daily coding tasks in a Next.js monorepo. Average across six real open-source repos was 8.2×. The initial graph build takes around ten seconds for a 500-file project, and it auto-updates on every file edit and git commit.

pip install code-review-graph
code-review-graph install

The install command auto-detects which AI tools you have and writes the right MCP configuration for each. After installing, restart your editor and ask Claude to build the graph for your project. Worth a closer look in this DEV post.

4. agent-browser — stop re-authenticating every session

agent-browser is a browser automation CLI for AI agents, built by Vercel Labs. It's not a token compressor in the same league as rtk or caveman, but it solves a workflow that wastes more tokens than people realize: re-running the auth flow every time Claude needs to inspect a deployed site, a staging environment, or a third-party dashboard.

Save the auth state once:

agent-browser --auto-connect state save ./my-auth.json

Then reuse it across every future session:

agent-browser --state ./my-auth.json open https://app.example.com/dashboard

Add it to a Claude Code workflow that drives a browser to verify a DeployHQ deploy, check a staging URL, or scrape a logged-in dashboard, and you stop burning tokens on the same login dance over and over.

# Global install
npm install -g agent-browser
agent-browser install

# Or as a Claude Code skill
npx skills add vercel-labs/agent-browser

See where your tokens go

The next two repos don't reduce your usage — they tell you what your usage actually is. That sounds boring until you realise most Claude Code users have no idea which sessions cost them the most or how close they are to a hard limit until the warning hits mid-task.

5. claude-usage — a local dashboard for tokens, costs, and history

claude-usage is a single-page dashboard that runs on localhost:8080, reads your Claude Code JSONL logs locally, and renders Chart.js views of token usage, costs, and session history. It auto-refreshes every 30 seconds and supports model filtering, so you can see at a glance whether your costs are coming from Sonnet runs, Opus reasoning, or cache reads.

It uses only the Python standard library — sqlite3, http.server, json, pathlib — so there's no pip install, no virtualenv to manage, no dependency updates to track. Clone, run, look.

git clone https://github.com/phuryn/claude-usage
cd claude-usage
python3 cli.py dashboard

If you're on a Pro or Max plan, the dashboard adds a progress bar showing where you are against the limit. That single visual changed how a few of us pace work — instead of the model started warning me at 4pm, you see the burn rate building all morning.

6. claude-usage-monitor — real-time terminal predictions

claude-usage-monitor is the other half of the visibility story. Where claude-usage is a browser dashboard, this is a terminal-resident monitor with live progress bars, current session data, burn-rate analysis, and — the real value — predictions about when you'll hit your session limit based on a 90th-percentile analysis of your last eight days of usage.

It auto-detects your plan, switches modes when you cross thresholds, and shows you cost projections in real time. For a Max-plan user running multiple agents in parallel, it's the difference between session ends mid-refactor with no warning and you have ~14 minutes of headroom at current burn.

# Recommended (uv)
uv tool install claude-monitor

# Or pip
pip install claude-monitor

It runs in a side terminal pane and gets out of the way. After a week, you start pacing your day around it.

How these stack

If you only install one, install rtk — terminal output is the cheapest and biggest source of wasted tokens. If you install two, add code-review-graph; for review-heavy workflows it's a step-change, not a marginal improvement. Caveman is the most polarising of the four cost-cutters, but devs who stick with it for a week never go back.

The two visibility tools are complementary, not redundant. claude-usage is the analytical view you check at end of day to understand spend. claude-usage-monitor is the heads-up display you keep open while working. Run both for a week and you'll have a much sharper sense of which prompting habits are expensive and which aren't.

A cleaner token budget also frees up runway for ambitious workflows that previously hit the wall — like driving Claude through a full deploy automation pipeline, generating production SQL queries, or comparing AI CLIs on real codebase tasks. If you're new to Claude Code itself, start with our terminal AI assistant primer. If your sessions are spawning noisy commits, our Co-Authored-By guide shows how to keep history clean. And to keep the model grounded in real, current docs instead of hallucinated APIs, layer in Context7.

A word on the $100/mo claim

Token-savings posts attract clickbait math. The honest version: rtk's 60-90% reduction on terminal commands and code-review-graph's 6.8-49× reduction on review tasks are real, but they apply to specific kinds of work. If you're a Max-plan user running multi-hour sessions on large codebases — the kind of user who hits the weekly limit before Wednesday — installing rtk and code-review-graph alone will plausibly save you a tier of overage or upgrade pressure each month. That's where the $100 number comes from.

If you're a Pro user occasionally asking Claude to write a unit test, you'll see longer sessions and faster context loading, but you won't recover real cash because you weren't spending it in the first place. Either way, all six repos are free, MIT or similarly permissive, and take under five minutes each to install. The downside is small. Try the four cost-cutters for a week, then add the two monitors and let the data tell you what stuck.

Questions or want to share which combo worked for you? Email support@deployhq.com or hit us up on @deployhq.

PR Radar vs GitHub Notifications vs Email: How Developers Actually Track Pull Requests

DeployHQ — Fri, 24 Apr 2026 12:32:48 +0000

If you've managed more than a handful of pull requests across more than one Git platform, you've probably built your own little tracking system out of whatever was free and already installed. A few browser tabs. Email filters. Maybe a Slack integration that someone turned on two years ago and nobody can remember the auth for. It works, until it doesn't — until the PR that needed the please merge today comment gets buried under twelve identical CI notifications, or until the GitLab side of your migration stays invisible for three hours because you only had the GitHub tab open.

This is a comparison of the ways developers actually track PRs today — including PR Radar, the open-source Chrome extension we built because none of the existing options did what we wanted. We'll be honest about where each one wins and where it falls short, and we'll end with the one question that decides which tool you actually need. It's the same format we used for our package manager benchmark and our transactional email API comparison — practical, developer-to-developer, and honest about the gaps.

The five options on the table

Before the comparison, here's the shortlist. We've stayed focused on tools that monitor PR status rather than tools that try to change your PR workflow (so Graphite, Aviator, and Reviewpad are out — they solve a different problem).

Email notifications — the default for GitHub, GitLab, and Bitbucket
GitHub's built-in notification inbox — the bell icon, the /notifications page
Slack integrations — GitHub for Slack, GitLab for Slack, Bitbucket's bot
GitHub-specific extensions — Refined GitHub, Notifier for GitHub
PR Radar — multi-platform dashboard in the browser toolbar

Option 1: Email — the default everyone ignores

Every Git host turns on email notifications by default. Every developer turns most of them off within a month.

The problem with email isn't that it's a bad channel. It's that PR events are high-frequency and low-information per message. A typical active PR generates email for:

The initial open
Every review comment
Every reply in a thread
Every push that re-triggers CI
Every CI status change
Merge or close

Multiply by 8–12 active PRs in a normal week and you've built a firehose. The signal-to-noise ratio collapses because every email looks roughly the same in the preview pane: a PR title, a repo name, and one line of context. You cannot tell at a glance which of your fifteen unread messages is CI failed on the PR that's blocking release and which is approving nit on a docs typo.

Where email wins: Audit trail. If you need a durable record of what happened and when, email is it. Good for compliance, useless for real-time awareness.

Where it fails: Real-time awareness, cross-platform visibility, CI status at a glance.

Option 2: GitHub's notification inbox

GitHub's inbox (the bell icon and /notifications) is better than email for one reason: it's scoped and threaded. A single PR becomes one inbox entry that updates in place instead of twenty separate emails.

It has genuine improvements over the last couple of years — filters, custom views, Participating vs All, per-repo mute. If you live entirely inside GitHub, the inbox is solid.

But it has three hard ceilings.

It's GitHub-only. If your team uses GitLab for infra and GitHub for apps, the inbox solves half your problem. The other half you track… somehow.

It doesn't show CI status inline. The inbox will tell you CI ran on this PR. It will not tell you whether it passed or failed without a click into the PR page. For a tool whose primary job is telling you what needs your attention, burying the pass/fail state behind a click is a miss.

It needs a tab open. The inbox icon lives inside github.com. If you closed the tab during a focus block, you find out about a failed deploy the next time you cmd-T your way back. Browser desktop notifications exist but are disabled by default and, even when on, only fire when a GitHub tab is already open.

Where it wins: Native, reliable, no extra auth, granular filters.

Where it fails: GitHub-only, no CI status in the list view, tab-bound.

Option 3: Slack integrations

Slack is where most engineering teams already are, so routing PR events into Slack seems obvious. And for a few specific use cases — a dedicated #deploys channel, a release-critical PR that the whole team is watching — it's the right tool.

For everyday PR tracking, Slack is a noise amplifier. A rebase-heavy afternoon on a single PR can push twenty notifications into a channel. The team stops reading them. Important signals (production deploy failed) end up in the same channel as unimportant ones (renovate bumped a patch version), with the same visual weight, both probably muted by Thursday.

There's also a coverage asymmetry. GitHub for Slack is mature. GitLab for Slack is functional. Bitbucket's Slack integration exists but feels like an afterthought. If you've got repos on all three, Slack gives you an uneven view of each one.

Where it wins: Team visibility on critical events, shared context during an incident.

Where it fails: Personal PR tracking, signal-to-noise, multi-platform parity.

Option 4: Refined GitHub and Notifier for GitHub

If you've looked for browser extensions for this before, you've hit two classic options.

Refined GitHub is excellent — dozens of polish-level improvements to github.com pages. But it enhances GitHub; it doesn't pull PR status out of GitHub into your toolbar. You still need to open the tab.

Notifier for GitHub does put a badge in your toolbar, but the badge counts unread notifications — not CI state, not review state. A red badge tells you there's something and nothing else. You click through to find out what.

Both are GitHub-only, both assume GitHub is your whole world, and neither addresses the core visibility problem if your work spans platforms.

Where they win: Free, lightweight, GitHub UX polish (Refined GitHub in particular is a staple).

Where they fail: Single-platform, no CI awareness in Notifier, no toolbar summary in Refined.

Option 5: PR Radar

PR Radar is the extension we built after rotating through all four options above and still ending up with a browser window full of tabs. It's a Chrome extension (Firefox and Edge in progress), MIT-licensed, open source, and free — no paid tier, no accounts, no backend at all. Links to the store listing and repo are at the end of the post.

The short version of what it does:

One toolbar popup with every open PR across GitHub, GitLab, and Bitbucket
Badge on the toolbar icon with a live pass / fail / running count for CI
Unresolved comment count per PR, pulled via GraphQL so the number is actually correct
Deployment status inline with clickable environment URLs
Desktop notifications and sound alerts when CI finishes (no tab required — it polls in a service worker)
One-click merge from the dashboard, across all three platforms
Stale PR dimming with a configurable threshold so your attention goes to the active ones
Keyboard shortcuts — j/k to move between PRs, o to open, / to search, ? for the full list

The design goal was minimum cognitive load: glance at the toolbar, see whether anything needs you, go back to what you were doing. If the badge is green, there is nothing to do. If it's red, you know exactly where to look. The same mindset drove our list of developer CLIs that AI agents use well — a good dev tool should compress ten decisions into one glance.

Privacy-wise, PR Radar doesn't send your tokens anywhere. Your personal access tokens sit in the browser's local storage, and the extension makes API calls directly from your browser to each Git platform. There is no PR Radar backend. We don't run analytics. There's no DeployHQ account required — the extension works whether or not you're a DeployHQ customer.

Side-by-side

Dimension	Email	GitHub Inbox	Slack	Refined / Notifier	PR Radar
GitHub	✅	✅	✅	✅	✅
GitLab	✅ (via email)	❌	⚠️ Uneven	❌	✅
Bitbucket	✅ (via email)	❌	⚠️ Uneven	❌	✅
CI status at a glance	❌	❌	⚠️ In channel	❌	✅ Badge + inline
Unresolved comment count	❌	❌	❌	❌	✅
Deploy status in PR list	❌	❌	❌	❌	✅
Works without a tab open	✅	❌	✅	❌	✅ Service worker
Sound / desktop alerts	❌	⚠️ If tab open	✅	❌	✅
Merge from the tool	❌	❌	❌	❌	✅ All 3 platforms
Cost	Free	Free	Free tier + Slack cost	Free	Free + open source
Privacy	Platform stores email	Platform	Slack + platform	Platform	100% local, no backend

The pattern is consistent: each mainstream option handles one or two of these well and treats the rest as out of scope. For developers who only use GitHub and already live in Slack, that's fine. For anyone working across platforms, the gaps add up fast.

The deployment connection

If you're reading this on the DeployHQ blog, there's a fair chance you care specifically about the last mile: the moment between CI passed and change is live. That moment is where PR tracking stops being a productivity nice-to-have and starts being a deployment-quality thing.

Two concrete examples:

Catching a broken deploy before the channel sees it. When CI includes a deploy step (either an automatic deployment from Git or a preview environment triggered by PR), the failure signal travels through the same notification pipes as every other CI event. In email or Slack, a failed deploy looks like every other failed check. In PR Radar, the toolbar flips red the moment the job changes state, with the deploy URL one click away. That's a four-second feedback loop instead of a forty-minute one.

Merging without a tab full of PRs. DeployHQ's one-click rollback and zero-downtime deployments are designed to make shipping cheap. The bottleneck in that flow is usually human: somebody has to decide the PR is ready and hit merge. If that decision point lives in a popup rather than on a PR page buried in a tab group, the whole cycle tightens.

Neither of these is the reason to install a browser extension on its own. But if you already care enough about deployment velocity to be reading this, the PR tracking side of the workflow probably deserves the same attention you've given your CI/CD pipeline and your deploy automation.

Who should pick which

Here's the actual decision tree.

You only use GitHub and you're fine with the inbox. Stay with it, maybe bolt on Refined GitHub for UI polish. No extension needed.

You only use GitHub but the inbox feels lossy. Try Notifier for GitHub for the toolbar badge. If you want CI status specifically and not just unread counts, PR Radar fits even in single-platform setups.

You use GitHub + GitLab or GitHub + Bitbucket. This is the case email, the inbox, and GitHub-specific extensions all fail at. A dedicated multi-platform tool is the only real answer. PR Radar is the one we built; there isn't much direct competition in the free / privacy-first slice of that category.

You're a team lead who wants team-wide visibility into deploys. Slack is still right for that — route release-critical events into a dedicated channel. Just don't try to use the same Slack integration for personal PR tracking; it's the wrong tool for the wrong granularity.

You care about privacy or you work on client repos with sensitive PR titles. PR Radar keeps everything local — tokens in browser storage, API calls direct to platforms, no backend, no analytics. Hosted PR tools generally require you to authorize an OAuth app that sees your PR content. That's a real trade-off worth knowing about, in the same category as picking which MCP servers you grant access to your codebase or how you wire Claude Code into Git.

Try it

PR Radar is free, open source (MIT), and takes about a minute to set up.

Install from the Chrome Web Store (Firefox and Edge builds are in progress on the GitHub releases page)
Star the repo on GitHub if it saves you a tab — it's how we know to keep investing in it
File an issue if a platform quirk breaks your setup; we read all of them

If you're already on DeployHQ, PR Radar closes the visibility gap between PR looks good and change is live without asking you to change anything about your deployment workflow. If you're not, it's still the fastest way we've found to stop tab-hopping between Git hosts.

Questions, platform-specific gotchas, or feature requests? Email us at support@deployhq.com or ping us on Twitter/X. If you'd rather build your own PR dashboard on top of the GraphQL APIs, the source is MIT-licensed and PRs are welcome.

Mailtrap vs SendGrid vs Mailgun: Best Email API for Node.js in 2026

DeployHQ — Wed, 15 Apr 2026 05:07:04 +0000

Mailtrap, SendGrid, and Mailgun are the three most common email APIs that Node.js developers use for transactional or promotional email sending. Each takes a different approach to SDK design, deliverability architecture, and pricing, so the right choice depends on what your team actually needs.

This comparison covers installation, deliverability infrastructure, API workflow capabilities, MCP support, and pricing. All three were tested by integrating their SDKs into a Node.js project and sending emails.

Quick Comparison Overview

All three tools offer straightforward npm installation, but there are differences worth noting in setup complexity, package size, and ecosystem maturity.

Email API	Setup Time	NPM Downloads / Week	SDK Size	TypeScript Support
Mailtrap	5 mins	28K+	90.4 kB	Yes
Mailgun	10-15 mins	360K+	1.3 MB	Yes
SendGrid	10-15 mins	1.65M+	17.4 kB	Yes

Installation and Setup Comparison

When integrating an email service into a deployment pipeline, you want an SDK that configures quickly and does not introduce brittle dependencies.

Mailtrap

Setup time: 5 minutes. Complexity: Easy.

npm install mailtrap

const { MailtrapClient } = require("mailtrap");

const client = new MailtrapClient({
  token: process.env.MAILTRAP_API_TOKEN,
});

const sender = { email: "hello@example.com", name: "Test" };

client.send({
  from: sender,
  to: [{ email: "recipient@example.com" }],
  subject: "Hello from Mailtrap",
  text: "This is a test email.",
});

The Mailtrap package follows a clean API design with intuitive REST principles. It does not require complex DNS setup for initial sandbox testing, so developers can configure their environment variables and fire off a test email right away.

Mailgun

Setup time: 10-15 minutes. Complexity: Medium to complex.

npm install mailgun.js form-data

const Mailgun = require("mailgun.js");
const formData = require("form-data");

const mailgun = new Mailgun(formData);
const mg = mailgun.client({
  username: "api",
  key: process.env.MAILGUN_API_KEY,
});

mg.messages.create("your-domain.com", {
  from: "hello@your-domain.com",
  to: ["recipient@example.com"],
  subject: "Hello from Mailgun",
  text: "This is a test email.",
});

Mailgun requires DNS configuration for domain verification before you can send production emails. The SDK also depends on form-data as a peer dependency, which adds a step. Understanding the email validation features adds initial overhead too.

SendGrid

Setup time: 10-15 minutes. Complexity: Medium.

npm install @sendgrid/mail

const sgMail = require("@sendgrid/mail");
sgMail.setApiKey(process.env.SENDGRID_API_KEY);

sgMail.send({
  to: "recipient@example.com",
  from: "hello@example.com",
  subject: "Hello from SendGrid",
  text: "This is a test email.",
});

The @sendgrid/mail package requires additional configuration for sender authentication and strict API key management. There are multiple ways to structure email payloads, which can be confusing during initial setup if you are working from the docs (they carry a lot of legacy content for different API versions).

Getting started verdict: Mailtrap has the lowest friction for a first send. SendGrid and Mailgun both take 10-15 minutes depending on DNS propagation and how familiar you are with their respective dashboards.

Deliverability and Infrastructure

How each service handles deliverability architecture matters more than raw setup speed once you are sending production emails.

Mailtrap

Mailtrap enforces strict separation between transactional and bulk message streams. This is an architectural decision, not just a UI toggle. Transactional emails (password resets, order confirmations, 2FA codes) run on a dedicated IP pool that is never affected by the reputation of your marketing sends. If a promotional campaign triggers spam complaints, your critical application notifications keep arriving. Mailtrap also offers a 99.99% uptime guarantee with compensation, and detailed analytics that track opens, clicks, and bounces for up to 30 days.

Mailgun

Mailgun focuses heavily on pre-send list quality. It validates email addresses by checking DNS MX records, disposable address databases, and mailbox existence against a 450+ billion email dataset. If you have older contact lists with unknown deliverability, this validation layer can meaningfully reduce your bounce rates before you even send. Mailgun also maintains automated suppression lists that remove hard bounces and spam complainers from future sends, which protects your sending domain over time.

SendGrid

SendGrid operates at a massive scale. Its infrastructure handles enterprise-level volume for both marketing and transactional email, backed by Twilio's network. It also offers native Handlebars template logic stored in the UI and programmatic automation for drip campaigns. For large organizations that need a single platform to handle everything from password resets to weekly newsletters, SendGrid's breadth is hard to match.

Deliverability verdict: Mailgun's pre-send validation against 450+ billion records and automated suppression lists give it the most complete deliverability toolkit. Mailtrap's stream separation is a solid architectural advantage for apps mixing transactional and promotional email. SendGrid's scale and Twilio-backed infrastructure make it the safest bet for high-volume senders.

API Workflow Capabilities

Creating Email Templates

SendGrid lets marketing teams store email templates directly in its UI using Handlebars syntax. Content updates don't require code deployments. Mailtrap and Mailgun offer full API control over templates, but developers need to manage the payload construction themselves.

Event Webhooks

Webhooks let your Node.js server passively listen for delivery events.

Mailtrap delivers full payload data for delivered, opened, and bounced events, with 40 internal retries every five minutes to make sure events are not dropped. Mailgun includes message IDs alongside click and bounce events, which is useful for debugging delivery issues. SendGrid tracks standard events but restricts free-tier users to a single endpoint.

Framework Integration

All three providers offer SDKs that work with Express.js, Next.js, NestJS, Fastify, and Koa. They all support standard async/await patterns and compile-time error checking through TypeScript. Framework compatibility is not a differentiator here.

API workflow verdict: SendGrid's Handlebars-based template system lets users update email content without code deployments, and the broader ecosystem means more community examples and integrations. Mailgun's message-ID tracking is the strongest option for debugging delivery issues. Mailtrap's webhook retry mechanism is worth noting for teams that need guaranteed event delivery.

MCP and Extensibility

All three tools support the Model Context Protocol (MCP) for extending AI capabilities into IDEs and terminal workflows.

Mailtrap provides an official MCP server focused on deliverability, template management, and multi-recipient sending. Mailgun offers an open-source MCP server for sending emails and retrieving analytics. SendGrid relies on community-created MCP servers for campaign management, which may require manual configuration.

Common MCP use cases for email include generating and testing HTML email templates via AI, querying bounce rates and delivery logs, and automating recipient list segmentation.

Extensibility verdict: Mailtrap and Mailgun both offer maintained MCP servers. SendGrid's community approach gives you more flexibility but less out-of-the-box reliability.

Pricing Comparison

Cost is often the deciding factor when scaling a Node.js application's email infrastructure.

Mailtrap

Free tier covers up to 1,000 emails. The Basic plan starts at $15/month for 10,000+ emails. The Business plan runs $85/month for 100,000+ emails. Higher tiers include 24/7 priority support and extended log retention.

Mailgun

Free tier allows 100 emails per day. The Foundation plan is $15/month for 10,000 emails. The Scale plan costs $90/month for 100,000 emails. Pricing gets less competitive at higher volumes, but the validation tools can save money by reducing bounces.

SendGrid

Free tier offers 100 emails per day on a 60-day trial. Essentials starts at $19.95/month for 50,000 emails. Pro costs $89.95/month for 100,000 emails. The pricing structure is complex with many add-ons, but makes sense for high-volume senders who need marketing and transactional email in one platform.

Pricing verdict: At lower volumes all three are competitive. Mailtrap and Mailgun both start at $15/month. SendGrid costs slightly more but includes a larger email allowance on its Essentials plan. The real cost differences emerge at scale and depend on which features you actually use.

Unique Strengths

Mailtrap: Strict separation of transactional and promotional streams. An official TypeScript SDK with zero unnecessary dependencies. A 99.99% uptime SLA with automatic webhook failure detection.

Mailgun: Industry-leading pre-send email validation against a 450+ billion record database. Batch sending to 1,000 recipients per API call using localized recipient variables.

SendGrid: The largest Node.js email ecosystem with 1.65 million weekly npm downloads, backed by Twilio's infrastructure. A unified API that handles both transactional coding and visual marketing campaigns.

Managing Email Credentials in Your Deployment Pipeline

Regardless of which email API you choose, never hardcode API keys in your application code. Inject them through environment variables:

const apiKey = process.env.EMAIL_API_KEY;
if (!apiKey) {
  throw new Error("EMAIL_API_KEY is missing from environment.");
}

This is a common pitfall, especially when switching between staging and production API keys for different email providers. A leaked SendGrid or Mailgun key in a public repo can result in your sending domain getting blacklisted within hours.

If you are deploying a Node.js app that sends email, your deployment tool should handle these secrets safely. In DeployHQ, you can store environment variables as part of your project's build pipeline configuration and inject them at deploy time. This keeps credentials out of your repository while ensuring each environment (staging, production) uses the correct API keys and SMTP settings.

You can also use DeployHQ's configuration file feature to template out .env files during deployment, swapping placeholders for real values stored in the deployment target settings. For teams running separate transactional and marketing email streams (which Mailtrap enforces by default), this means you can store different API tokens per deployment target and avoid accidentally sending test emails through your production pipeline.

Recommendations by Use Case

For developer and product teams shipping transactional email quickly: Mailtrap. The 5-minute setup and strict stream separation let you get to production without surprises. The SDK is small, typed, and does not pull in unnecessary dependencies.

For teams managing older or unverified contact lists: Mailgun. The validation API will reduce your bounce rates before emails ever leave your server. The batch sending feature (up to 1,000 recipients per API call with recipient variables) is also useful for teams sending personalized notifications at moderate scale.

For enterprise marketing teams that need campaigns and transactional email in one platform: SendGrid. The unified ecosystem and Twilio backing handle both use cases, and the 1.65 million weekly npm downloads mean you will find answers to most integration questions on Stack Overflow.

Making Your Choice

There is no wrong choice among these three. Mailtrap, SendGrid, and Mailgun are all actively maintained, well-documented, and capable. All three support async/await, TypeScript, and the major Node.js frameworks. Start with the one that matches your timeline and email types, then evaluate further as your sending volume grows.

The broader trend across all three providers is convergence around MCP support, TypeScript-first SDKs, and better webhook reliability. Where they still diverge is in deliverability architecture and pricing models. For deployment workflows specifically, the most important factor is how cleanly the SDK integrates with your existing environment variable management and CI/CD pipeline.

Frequently Asked Questions

Which email API is best for a Node.js beginner?

Mailtrap has the simplest setup at around 5 minutes, with a single npm package and no peer dependencies. SendGrid is also straightforward but has more configuration options that can be confusing initially. If you just need to get a transactional email working quickly, Mailtrap or SendGrid are your best bets.

Can I switch email providers later without rewriting my application?

Yes, if you abstract your email sending behind a service layer. All three providers use similar patterns (API key authentication, JSON payloads, async sending), so swapping one for another typically means changing the SDK import and adjusting the payload format. Keeping your API keys in environment variables rather than hardcoded makes the switch even simpler.

Do I need a dedicated IP address for transactional email?

Not necessarily. All three providers offer shared IP pools that work well for most applications. Dedicated IPs become relevant when you send high volumes (50,000+ emails per month) and want full control over your sender reputation. Mailtrap and SendGrid offer dedicated IPs on higher-tier plans; Mailgun includes them on the Scale plan and above.

How do I test emails without sending to real recipients?

Mailtrap was originally built as an email testing tool — its sandbox captures emails in a virtual inbox so you can inspect HTML rendering, spam scores, and headers without sending to real addresses. SendGrid and Mailgun both support sandbox modes as well, though the setup requires additional configuration.

What happens if my email API goes down during a deployment?

Your application should handle email API failures gracefully with retry logic and a message queue. None of these providers guarantee 100% uptime (Mailtrap offers 99.99%, the others are similar). Using DeployHQ's zero-downtime deployments ensures your application stays available during deploys, but your email error handling should account for temporary API outages regardless of provider.

Is it safe to use free tiers in production?

Free tiers are fine for low-volume applications, but they come with limitations. Mailtrap's free plan caps at 1,000 emails per month. SendGrid and Mailgun limit you to 100 emails per day. Beyond testing and early-stage projects, you will likely need a paid plan for reliable production sending with higher rate limits and better support.

Ready to streamline your Node.js deployments? Get started with DeployHQ and automate your deployment pipeline today.

Have questions? Reach out at support@deployhq.com or find us on X (@deployhq).

CLIs or MCP for Coding Agents? A Practical Comparison

DeployHQ — Mon, 13 Apr 2026 08:34:15 +0000

This is Part 5 of our series on AI coding assistants for developers. See also: Getting Started with Claude Code, Getting Started with OpenAI Codex CLI, Getting Started with Google Gemini CLI, and Comparing AI CLI Coding Assistants.

Your AI coding agent can read files, run commands, and edit code. But how does it actually connect to the tools and services it needs? In 2026, there are two dominant approaches: command-line interfaces (CLIs) and the Model Context Protocol (MCP). Both give coding agents access to external capabilities — but they work in fundamentally different ways, with real consequences for context quality, reliability, and what your agent can actually do.

This isn't an abstract protocol debate. The interface you choose directly affects how well your agent understands your codebase, how accurately it executes tasks, and how much manual oversight you need to provide. Let's break down what's similar, what's different, and when each approach makes sense.

What We Mean by CLIs and MCPs

Before comparing them, let's be precise about what each term means in the context of coding agents.

CLIs: The Agent Shells Out

When a coding agent uses a CLI tool, it constructs a shell command, executes it in a subprocess, and parses the text output. This is the oldest and most universal integration pattern. Your agent might run git log --oneline -10 to see recent commits, npm test to run your test suite, or curl to hit an API endpoint.

The agent treats the CLI as a black box: it sends a string, gets a string back, and interprets the result using its language understanding.

MCP: A Structured Tool Protocol

The Model Context Protocol is an open standard that defines a JSON-RPC interface between AI models and external tools. Instead of executing arbitrary shell commands, the agent calls named tools with typed parameters and receives structured JSON responses.

An MCP server might expose a search_posts tool that accepts { "query": "deployment", "status": "published" } and returns a typed array of post objects — complete with IDs, titles, dates, and metadata. The agent never needs to parse text output or guess at field meanings.

What They Have in Common

Despite the architectural differences, CLIs and MCP share several characteristics:

Both extend agent capabilities. Whether your agent runs gh pr list or calls an MCP tool named list_pull_requests, the end result is the same: the agent gains access to information and actions beyond its training data. Both approaches turn a conversational AI into something that can interact with real systems.

Both require trust boundaries. A CLI command can delete files; an MCP tool can publish a blog post. In both cases, you need permission models. Claude Code uses approval prompts for shell commands; MCP servers define their own tool permissions. The security concern is identical — you're giving an AI agent the ability to affect real systems.

Both work across all major coding agents. Claude Code, Codex CLI, and Gemini CLI all support both shell execution and MCP servers. (If you're still choosing between these three, our comparison of AI CLI coding assistants covers the differences in detail.) The specific configuration differs, but the concept is universal. If you're building an integration, either approach will work with the tools your team already uses.

Both can be composed. Agents regularly chain multiple CLI commands together (git add . && git commit -m "fix" && git push), and they can chain multiple MCP tool calls in sequence. Complex workflows are possible with either approach.

Where They Differ

Here's where the comparison gets interesting — and where the choice actually matters for your development workflow.

1. Output Structure: Text vs. Typed Data

This is the single biggest difference, and it cascades into nearly every other comparison point.

CLI output is unstructured text. When your agent runs ls -la, it gets a blob of text that it must parse using pattern matching and language understanding. This works remarkably well for simple commands, but it introduces ambiguity. Does that column represent file size or block count? Is that date in DD/MM or MM/DD format? The agent is constantly inferring structure from text.

MCP responses are structured JSON. When your agent calls an MCP tool, it gets back typed fields with known semantics. A post object has a published_at field that's always a Unix timestamp, a title that's always a string, and a categories array that's always a list of IDs. There's no ambiguity to resolve.

This matters most when agents need to make decisions based on the data. An agent parsing git log output might misinterpret a commit message that contains a date-like string. An agent receiving structured commit objects from a Git MCP server won't have that problem.

2. Discoverability: Man Pages vs. Tool Schemas

CLI tools require the agent to know what exists. The agent needs prior knowledge (from training data) about which commands are available, what flags they accept, and what their output looks like. If you have a custom deployment script at ./scripts/deploy.sh, the agent won't know about it unless you tell it — or it happens to find it while exploring your project.

MCP servers declare their capabilities. When an agent connects to an MCP server, it receives a complete list of available tools with descriptions, parameter schemas, and return types. The agent knows exactly what it can do without any prior knowledge. This is especially powerful for domain-specific tools — your custom DeployHQ MCP server doesn't need to be in the model's training data for the agent to use it effectively.

3. Context Efficiency: Tokens Matter

Every piece of information the agent processes consumes tokens from its context window. This has real cost and performance implications.

CLI output is verbose and unstructured. Running docker ps might return 20 lines of formatted table output when the agent only needed the container ID and status. The agent ingests all of it. Multiply this across dozens of commands in a complex task, and you're burning significant context on formatting, headers, and irrelevant columns.

MCP responses are precise. An MCP tool can return exactly the fields the agent needs. If you only want post titles and IDs, the MCP server returns just that — no extra columns, no formatting overhead, no ASCII table borders. For agents working on long, multi-step tasks, this efficiency compounds significantly.

Here's a concrete example. Fetching the last 10 blog posts via CLI might look like:

curl -s https://api.example.com/posts?limit=10 | jq '.[] | {id, title, status}'

That raw JSON response might be 2,000 tokens. The equivalent MCP call returns the same data in a pre-structured format that the agent can consume in roughly 800 tokens — because there's no HTTP headers, no jq processing, and no raw response wrapping.

4. Error Handling: Exit Codes vs. Typed Errors

CLI errors are inconsistent. Some tools use exit codes, some print to stderr, some return error messages on stdout, and some do all three in different combinations. An agent parsing CLI output needs to handle all these patterns — and sometimes the error is actually a warning that doesn't indicate failure.

MCP errors follow a standard format. The protocol defines error responses with codes, messages, and optional details. The agent always knows whether a call succeeded or failed, and can make reliable decisions about retry logic, fallback strategies, or error reporting.

5. Security Model: Sandbox vs. Scoped Permissions

CLI access is broad. When you give an agent shell access, it can potentially run any command your user account can execute. Most coding agents mitigate this with approval prompts, but the underlying capability is unrestricted. A malicious or confused agent could run rm -rf / if the permission check fails.

MCP access is scoped by design. Each MCP server exposes only its specific tools. A blog management MCP server can't access your filesystem; a database MCP server can't run shell commands. The attack surface is naturally smaller. If an MCP server's token has read-only permissions, no amount of clever prompting can make it write data.

This becomes especially important when agents operate with reduced oversight — in automated pipelines, background tasks, or full auto modes.

6. State and Authentication

CLIs inherit the user's environment. Your shell's PATH, environment variables, SSH keys, and authentication tokens are all available to CLI commands. This is convenient — git push just works because your SSH agent is running — but it also means the agent has access to all your credentials.

MCP servers manage their own auth. Each server handles its own authentication, typically through API tokens or service accounts configured when the server starts. This creates clear boundaries: your Google Search Console MCP server has its own service account credentials that are separate from your shell environment.

Comparison Summary

Dimension	CLI	MCP
Output format	Unstructured text	Typed JSON
Discoverability	Requires prior knowledge	Self-describing schemas
Context efficiency	Verbose (high token cost)	Precise (low token cost)
Error handling	Inconsistent across tools	Standardised protocol
Security scope	Broad shell access	Scoped per server
Auth model	Inherits user environment	Isolated per server
Setup complexity	Zero (tools already installed)	Moderate (server config needed)
Universality	Any CLI tool works	Only MCP-enabled services
Ecosystem maturity	Decades of tools	Growing rapidly (2024+)
Offline capability	Full	Depends on server

Which Provides Better Context for Coding Agents?

If you're optimising for agent performance — fewer hallucinations, more accurate tool use, better multi-step reasoning — MCP has a clear structural advantage. Typed data, self-describing schemas, and efficient token usage all contribute to higher-quality agent behaviour.

But that doesn't mean you should replace all CLIs with MCP servers. The practical answer is more nuanced:

Use MCP for domain-specific integrations. If you regularly interact with a specific service — your blog platform, deployment tool, monitoring system, or database — an MCP server gives the agent richer context and more reliable interactions. This is why tools like the DeployHQ MCP server exist: they provide structured access to deployment management that no CLI could match.

Use CLIs for general-purpose operations. File system operations, Git commands, package management, and build tools are universal. They work everywhere, require no setup, and agents handle them well. There's no benefit to wrapping npm install in an MCP server — the CLI works perfectly for this.

Use both together. The most effective setup in 2026 combines both approaches. Your agent uses CLIs for general development tasks and MCP servers for specialised integrations. Claude Code, for example, natively supports both — you can run shell commands and call MCP tools in the same conversation, letting the agent choose the best approach for each step.

What This Means for Your Deployment Workflow

For teams using automated Git deployments, the CLI-vs-MCP choice has practical implications:

Git operations stay CLI-based. Your agent commits, pushes, and manages branches through standard Git commands. This is well-understood, universal, and effective.

Deployment management benefits from MCP. Checking deployment status, triggering rollbacks, or inspecting server configurations are tasks where structured data matters. An MCP server that returns deployment status as { "status": "success", "deployed_at": "2026-04-12T10:30:00Z", "commit": "abc1234" } gives the agent far better context than parsing HTML or text output from a dashboard.

Content operations are ideal for MCP. If your workflow includes managing blog content alongside code — writing deployment guides, updating documentation, managing SEO — an MCP server provides the structured access that makes agents genuinely useful for content workflows.

The pattern we see with teams using DeployHQ is straightforward: Git CLI for code, MCP for everything else that has an API. This gives agents the broadest capabilities with the best context quality.

The Future: Convergence

The boundary between CLIs and MCP is already blurring. Some newer CLI tools output structured JSON by default. MCP servers can wrap existing CLIs to add structure. And coding agents are getting better at parsing unstructured output.

But the trend is clear: as agents take on more complex, multi-step tasks with less human oversight, structured interfaces become more important — not less. The more an agent operates autonomously, the more it benefits from unambiguous, typed data.

If you're building tools for AI agents today, MCP is worth the investment. If you're using agents for development work, configure both CLIs and the MCP servers that match your workflow. The agents that perform best are the ones with the richest, most structured context available.

Frequently Asked Questions

Can I use MCP and CLIs together in the same agent session?

Yes. All major coding agents — Claude Code, Codex CLI, and Gemini CLI — support both shell commands and MCP tool calls in the same session. The agent picks the most appropriate interface for each task automatically. You don't need to choose one or the other.

Do MCP servers replace the need for CLI tools?

No. MCP servers complement CLIs rather than replacing them. CLIs excel at general-purpose operations like file management, Git, and build tools. MCP servers are best for domain-specific services where structured data and scoped permissions matter. The most effective setups use both.

Is MCP harder to set up than just using CLIs?

MCP requires initial configuration — you need to install and configure each server, provide API tokens, and register them with your coding agent. CLIs, by contrast, typically just work with your existing shell environment. However, the setup is usually a one-time task, and the improved agent performance often justifies the upfront effort.

Does using MCP reduce token costs?

Generally yes. MCP responses are structured and concise, which means less token usage per interaction compared to parsing verbose CLI output. For agents running long, multi-step tasks or operating at scale, this efficiency can meaningfully reduce costs — especially with pay-per-token pricing models.

Which approach is more secure?

MCP has a structural security advantage because each server exposes only specific capabilities with scoped permissions. CLI access grants broader system access by default. However, both approaches require proper configuration — MCP servers need secure token management, and CLI access needs appropriate permission prompts. Neither is inherently safe without proper setup.

AI coding agents are most effective when they have the right context, delivered through the right interface. For general development tasks, your terminal's CLI tools remain indispensable. For specialised integrations — content management, deployment automation, monitoring, and APIs — MCP provides the structured context that helps agents work accurately and efficiently.

The best setup isn't one or the other. It's both, configured to match your workflow.

Ready to add structured deployment management to your AI coding workflow? DeployHQ integrates with all major AI coding assistants through both CLI and MCP, giving your agents the context they need to manage deployments confidently. Get started for free.

For questions or feedback, reach out at support@deployhq.com or on Twitter/X.

Deploy from Gitea to Your Server Automatically

DeployHQ — Sat, 11 Apr 2026 07:22:39 +0000

Gitea is quietly becoming the go-to self-hosted Git service. It's lightweight (runs on a Raspberry Pi), easy to install, and gives you full control over your source code without depending on GitHub or GitLab's infrastructure.

But Gitea has one notable gap: no built-in CI/CD. Gitea Actions exists but is still maturing and requires a separate runner instance. For teams that just want to push code and have it deployed to their server, that's a lot of infrastructure for a simple requirement.

Here's how to add fully automated deployments to your Gitea workflow in under 10 minutes, using webhooks and DeployHQ.

Why Gitea Needs an External Deployment Tool

Gitea is intentionally minimal — it's a Git hosting service, not a DevOps platform. That's a feature, not a bug. But it means deployment is left as an exercise for the user.

The common approaches:

Gitea Actions — still in development, requires a dedicated runner, modelled after GitHub Actions but with fewer marketplace actions available
Drone CI / Woodpecker CI — full CI/CD systems that integrate with Gitea, but they're heavy for simple push to deploy workflows
Manual SSH — ssh server 'cd /var/www && git pull' works but breaks the moment you need build commands or multiple servers
Webhook-based deployment — a lightweight service watches for push events and deploys automatically

The webhook approach hits the sweet spot: no CI infrastructure to maintain, no YAML pipelines to write, and it works with any Gitea installation.

The Architecture

flowchart LR
    A[Developer] -->|git push| B[Gitea Instance]
    B -->|webhook POST| C[DeployHQ]
    C -->|git clone via SSH| B
    C -->|build commands| D[Build Server]
    D -->|changed files via SSH/SFTP| E[Production Server]

When you push to Gitea, a webhook fires. DeployHQ receives the notification, clones the latest code from your Gitea repo, runs any build commands, and deploys the changed files to your server. The entire cycle takes seconds.

Step-by-Step Setup

1. Create a DeployHQ Project

When asked for your repository, choose Enter repository URL manually — Gitea isn't in the OAuth provider list since it's self-hosted.

Enter your Gitea repository URL. You have two options:

SSH (recommended):

git@gitea.yourserver.com:username/repo.git

HTTPS with access token:

https://gitea.yourserver.com/username/repo.git

For SSH, DeployHQ will generate an SSH key pair. Copy the public key.

2. Add the SSH Key to Gitea

In your Gitea repository:

Go to Settings → Deploy Keys
Click Add Deploy Key
Paste the DeployHQ public key
Title it DeployHQ
Leave Enable Write Access unchecked (read-only is sufficient)

Alternatively, add the key to your Gitea user account under Settings → SSH/GPG Keys for access to all your repositories.

3. Configure Your Server in DeployHQ

Add your deployment target:

Protocol: SSH/SFTP
Hostname: your-production-server.com
Username: your deploy user
Authentication: SSH key (add DeployHQ's key to the server's authorized_keys)
Deployment Path: /var/www/myapp/ (or your web root)

4. Set Up Build Commands (If Needed)

If your project needs a build step:

cd %path% && npm ci && npm run build

Set the Deployment Subdirectory if you're deploying build output (e.g., dist/ for static sites, build/ for React apps).

5. Configure the Webhook in Gitea

This is where Gitea and DeployHQ connect. In DeployHQ, go to your project and find the Webhook URL (under project settings or on the servers page).

In Gitea:

Go to your repository → Settings → Webhooks
Click Add Webhook → choose Gitea
Target URL: paste the DeployHQ webhook URL
HTTP Method: POST
Content Type: application/json
Trigger On: Push Events
Active: checked
Click Add Webhook

Test it by clicking the Test Delivery button. You should see a 200 response.

6. Push and Deploy

Make a change, commit, and push:

echo "test" >> README.md
git add -A && git commit -m "Test deployment" && git push

Gitea fires the webhook → DeployHQ clones, builds, and deploys. Check the deployment log in DeployHQ to see exactly which files were transferred.

Branch-Based Deployments

Map different branches to different servers for a staging/production workflow:

Branch	Server	Environment
`main`	production-server.com	Production
`develop`	staging-server.com	Staging
`feature/*`	—	Not deployed (review locally)

In DeployHQ, add multiple servers and assign each to a specific branch. Pushing to develop deploys to staging. Merging to main deploys to production.

Handling Self-Signed Certificates

If your Gitea instance uses a self-signed HTTPS certificate, DeployHQ's HTTPS clone will fail certificate verification. Two solutions:

Use SSH instead of HTTPS — SSH cloning doesn't involve TLS certificates
Use a real certificate — Let's Encrypt is free and works with any domain

SSH is the simpler fix and is recommended regardless of certificate situation — it's faster and avoids password/token management.

Gitea Behind a Firewall

If your Gitea instance isn't publicly accessible, DeployHQ can't reach it for webhook delivery or Git cloning. Options:

Open port 22 (SSH) to DeployHQ's IPs — check DeployHQ's documentation for the IP list
Use a reverse SSH tunnel — more complex but avoids opening firewall ports
Mirror to a public Git host — Gitea can mirror to GitHub/GitLab, and DeployHQ clones from there

For most setups, opening SSH access from DeployHQ's IPs is the simplest approach.

Comparison: Gitea Deployment Options

Tool	Setup time	Maintenance	Build support	Multi-server	Cost
DeployHQ	~10 min	None	Yes (npm, Composer, etc.)	Yes	Free for 1 project
Gitea Actions	30-60 min	Runner maintenance	Yes (via Actions)	Custom scripting	Free (self-hosted)
Drone CI	30-60 min	Server + runners	Yes (Docker-based)	Custom config	Free (OSS edition)
Woodpecker CI	30-60 min	Server + agents	Yes (Docker-based)	Custom config	Free
Manual `git pull`	5 min	Error-prone	No	No	Free
Custom webhook script	1-2 hours	Script maintenance	Custom	Custom	Free

DeployHQ wins on setup time and maintenance. Drone/Woodpecker win if you need full CI (testing, multi-stage pipelines, matrix builds). Gitea Actions will likely become the default choice once it matures.

Multi-Repository Deployments

If your project spans multiple Gitea repositories (frontend + backend, or a main app + shared library), create separate DeployHQ projects for each. Each project has its own webhook, build configuration, and server targets.

For monorepos on Gitea, use DeployHQ's deployment subdirectory feature to deploy specific directories from the repository.

Gitea gives you independence from hosted Git providers. Adding DeployHQ gives you automated deployments without the complexity of running a full CI/CD system. Push to Gitea, and your code is live — simple as that.

If you're using GitHub or GitLab alongside Gitea, DeployHQ works with all of them from a single dashboard.

Start deploying from Gitea — set up takes about 10 minutes.

Questions about connecting your Gitea instance? Contact support@deployhq.com or reach us on Twitter/X.

How to Deploy EmDash with DeployHQ

DeployHQ — Thu, 09 Apr 2026 16:28:31 +0000

EmDash is a full-stack TypeScript CMS built on Astro — often described as the spiritual successor to WordPress. It combines a modern admin interface with Astro's rendering performance, Portable Text for structured content, and passkey-first authentication. If you're building a content-driven site with EmDash and need reliable, repeatable deployments from Git, DeployHQ makes the process straightforward.

In this guide, you'll set up an EmDash project for Node.js deployment, connect it to DeployHQ, configure your build pipeline, and deploy to a VPS or cloud server with zero manual file transfers.

What Is EmDash?

EmDash is an open-source CMS that runs as an Astro integration. Unlike traditional CMSs that bolt a content API onto a separate frontend, EmDash ships everything in one project — the admin panel, content editor, authentication, media management, and your frontend templates.

A few things that set EmDash apart:

Astro-native : Your site is an Astro project. EmDash adds the CMS layer as an integration, so you keep full control over routing, components, and rendering.
Portable Text editor : Content is stored as structured JSON (via TipTap), not raw HTML. This makes content reusable across different presentation formats.
Passkey-first auth : No passwords by default. Users authenticate with WebAuthn passkeys, with OAuth and magic links as fallbacks.
Schema-in-database : Content collections are defined in the database, not in code files. This means editors can create new collections without touching the codebase.
Plugin system : Extensible via a definePlugin() API with sandboxed execution on Cloudflare or in-process on Node.js.

EmDash supports multiple deployment targets — Cloudflare Workers, Docker containers, or plain Node.js servers. This guide focuses on Node.js deployment via DeployHQ, which covers VPS hosting, cloud instances, and dedicated servers.

Prerequisites

Before starting, make sure you have:

Node.js 22.12.0 or later installed on both your local machine and your deployment server
A Git repository (GitHub, GitLab, or Bitbucket) containing your EmDash project
A DeployHQ account — you can sign up for a free trial if you don't have one
SSH access to your server with Node.js 22+ installed
A process manager like PM2 or systemd configured on your server

If you haven't created an EmDash project yet, scaffold one with:

npm create emdash@latest my-site
cd my-site
npm install

This generates an Astro project with EmDash pre-configured. The scaffolder lets you choose from blog, marketing, or portfolio templates.

Preparing EmDash for Production

EmDash requires server-side rendering — it's a full-stack CMS, not a static site generator. Your Astro config must use the Node.js adapter in standalone mode.

Configure the Astro Adapter

Open your astro.config.mjs and verify the Node.js adapter is set to standalone:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import emdash from 'emdash';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
  integrations: [emdash()],
});

The standalone mode is critical — it produces a self-contained server entry point at ./dist/server/entry.mjs that you can run directly with Node.js. The alternative middleware mode is for platforms like Express where you manage the HTTP server yourself, but standalone is simpler for DeployHQ deployments.

Generate Authentication Secrets

EmDash needs two secrets for production: one for signing session cookies and another for preview URLs. Generate them locally:

npx emdash auth secret

This outputs a cryptographically secure random string. Run it twice — once for EMDASH_AUTH_SECRET and once for EMDASH_PREVIEW_SECRET. Save both values; you'll add them as environment variables in DeployHQ.

Choose Your Database

EmDash supports several database backends. For a Node.js deployment via DeployHQ, the practical options are:

Database	Best For	Configuration
SQLite	Single-server deployments	Set `DATABASE_PATH` to a persistent directory
PostgreSQL	Multi-server or production-critical sites	Set `DATABASE_URL` connection string
libSQL (Turso)	Remote SQLite with replication	Set `LIBSQL_DATABASE_URL` and `LIBSQL_AUTH_TOKEN`

SQLite is the simplest choice for a single VPS — no external database server needed. Just make sure the database file lives on a persistent volume, not in the deployment directory (since DeployHQ replaces files on each deploy).

For SQLite, create a data directory outside your deployment path:

# On your server, create a persistent data directory
mkdir -p /var/data/emdash
chown deploy:deploy /var/data/emdash

Then set the environment variable to point there:

DATABASE_PATH=/var/data/emdash/emdash.db

Add a Start Script

Verify your package.json includes a start script:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "start": "node ./dist/server/entry.mjs",
    "bootstrap": "emdash init && emdash seed"
  }
}

The build command compiles your Astro project into the dist/ directory. The start command runs the compiled server. DeployHQ will execute build during deployment and your process manager will run start on the server.

Setting Up DeployHQ

With your EmDash project in Git and your server ready, connect everything through DeployHQ.

Create a New Project

Log in to DeployHQ and click New Project
Name it (e.g., EmDash Blog) and select the server region closest to your deployment target
Connect your Git repository — DeployHQ supports GitHub, GitLab, Bitbucket, and self-hosted Git servers

Configure the Server

Add your deployment server under Servers in the project settings:

Click New Server
Choose SSH/SFTP as the protocol
Enter your server hostname, SSH port, and the deploy user credentials
Set the Deployment Path to where your application lives, for example /var/www/emdash
Test the connection to verify DeployHQ can reach your server

Configure the Build Pipeline

This is where DeployHQ handles your Node.js build. Navigate to Build Pipeline in your project settings:

Enable the build pipeline
Select Node.js 22 as the build environment
Add the build commands:

npm ci
npm run build

Using npm ci instead of npm install ensures a clean, reproducible install from your lockfile — important for consistent deployments.

DeployHQ's build pipeline runs these commands in an isolated container, compiles your Astro project, and then deploys only the output files to your server. This means your server doesn't need to run npm install or npm run build — it just receives the compiled application.

Set Environment Variables

Under Environment Variables in your project settings, add:

Variable	Value
`EMDASH_AUTH_SECRET`	Your generated auth secret
`EMDASH_PREVIEW_SECRET`	Your generated preview secret
`DATABASE_PATH`	`/var/data/emdash/emdash.db` (for SQLite)
`HOST`	`0.0.0.0`
`PORT`	`4321` (or your preferred port)

If you're using PostgreSQL instead, replace DATABASE_PATH with DATABASE_URL pointing to your connection string.

DeployHQ encrypts environment variables at rest, so your secrets are protected. These variables are available during the build step and can also be written to a .env file on the server if your application reads from one.

Configure Deployment Exclusions

Not every file needs to reach your server. Under Excluded Files , add:

src/
tests/
node_modules/
.git/
tsconfig.json
astro.config.mjs
README.md

Wait — you actually need node_modules on the server because dist/server/entry.mjs requires runtime dependencies. There are two approaches:

Approach A — Deploy node_modules (simpler): Don't exclude node_modules. DeployHQ transfers the full project including dependencies. This is slower but requires no server-side commands.

Approach B — Install on server (cleaner): Exclude node_modules and add a post-deploy SSH command to install production dependencies:

cd /var/www/emdash && npm ci --omit=dev

Approach B is preferred for larger projects because it only installs production dependencies, keeping the server lean.

Deploying EmDash

First Deployment

Your first deployment needs extra setup because the database doesn't exist yet. After the initial deploy completes:

SSH into your server
Navigate to your deployment directory
Run the bootstrap command to initialise the database:

cd /var/www/emdash
npm run bootstrap

This creates the database schema and optionally seeds sample content. You only need to run this once.

Start the application:

# Using PM2 (recommended)
pm2 start dist/server/entry.mjs --name emdash

# Or using systemd (see next section)

Visit http://your-server:4321/_emdash/admin to complete the setup wizard — set your site title, tagline, and register your admin passkey.

Set Up a Process Manager

For production, use PM2 or systemd to keep EmDash running and restart it on crashes or reboots.

PM2 ecosystem file (ecosystem.config.cjs):

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'emdash',
    script: './dist/server/entry.mjs',
    env: {
      HOST: '0.0.0.0',
      PORT: 4321,
      DATABASE_PATH: '/var/data/emdash/emdash.db',
      NODE_ENV: 'production',
    },
    instances: 1,
    autorestart: true,
    max_memory_restart: '512M',
  }],
};

Note: if you're using SQLite, keep instances: 1. SQLite doesn't handle concurrent writes from multiple processes well. For multi-instance deployments, switch to PostgreSQL.

systemd service (/etc/systemd/system/emdash.service):

[Unit]
Description=EmDash CMS
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/emdash
ExecStart=/usr/bin/node dist/server/entry.mjs
Restart=on-failure
Environment=NODE_ENV=production
Environment=HOST=0.0.0.0
Environment=PORT=4321
Environment=DATABASE_PATH=/var/data/emdash/emdash.db
EnvironmentFile=/var/www/emdash/.env

[Install]
WantedBy=multi-user.target

Automate Restarts with Post-Deploy Commands

After each deployment, EmDash needs to restart so it picks up the new code. Add a post-deploy SSH command in DeployHQ under SSH Commands → After Deployment :

cd /var/www/emdash && pm2 restart emdash

Or for systemd:

sudo systemctl restart emdash

This ensures every successful deployment automatically restarts the application without manual intervention.

Subsequent Deployments

After the initial setup, the deployment workflow is:

Push code changes to your Git repository
DeployHQ detects the push (via webhook) and starts a deployment
The build pipeline runs npm ci && npm run build
Compiled files are transferred to your server
The post-deploy command restarts the application

You can also configure DeployHQ to deploy automatically on every push to your main branch, or keep deployments manual and trigger them from the DeployHQ dashboard.

Deployment Architecture

Here's how the pieces fit together:

flowchart LR
    A[Git Push] --> B[DeployHQ]
    B --> C[Build Pipeline<br/>npm ci + astro build]
    C --> D[Transfer Files<br/>via SSH]
    D --> E[VPS / Cloud Server]
    E --> F[PM2 / systemd<br/>Restart]
    F --> G[EmDash Running<br/>port 4321]
    G --> H[Reverse Proxy<br/>nginx / Caddy]
    H --> I[Public Traffic<br/>HTTPS on port 443]

DeployHQ handles steps A through F. You configure the reverse proxy once during initial server setup.

Setting Up a Reverse Proxy

In production, you'll want a reverse proxy in front of EmDash to handle HTTPS, compression, and static asset caching. Here's a minimal nginx configuration:

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

If you prefer Caddy, the configuration is even simpler:

your-domain.com {
    reverse_proxy localhost:4321
}

Caddy handles TLS certificates automatically via Let's Encrypt — no manual certificate setup needed.

Troubleshooting

Build Fails with Cannot find module Errors

This usually means dependencies aren't installed correctly. Make sure your package-lock.json is committed to Git. DeployHQ's build pipeline runs npm ci, which requires a lockfile. If you're using pnpm locally, either switch DeployHQ to use pnpm install && pnpm build or add a package-lock.json alongside.

Application Starts but Admin Panel Returns 404

EmDash's admin routes live under /_emdash/admin. Make sure your Astro config has output: 'server' — if it's set to 'static' or 'hybrid', the server-side routes won't work.

Database Errors After Deployment

If you're using SQLite and see database is locked or no such table errors:

Verify DATABASE_PATH points to a directory outside the deployment path (so it persists between deployments)
Make sure the deploy user has write permissions to the database directory
Run npm run bootstrap if the database hasn't been initialised yet

Passkey Authentication Fails

Passkeys require HTTPS. If you're testing over plain HTTP, passkey registration and login will fail. Set up your reverse proxy with TLS first, or use the dev bypass endpoint for initial testing:

https://your-domain.com/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin

Remove this bypass in production by ensuring NODE_ENV=production is set.

Deployment Succeeds but Site Shows Old Content

The post-deploy restart command might not be running. Check the DeployHQ deployment log for SSH command output. Also verify that PM2 or systemd is actually restarting the correct process — run pm2 list or systemctl status emdash on the server to confirm.

Frequently Asked Questions

Can I use DeployHQ's atomic deployments with EmDash?

Yes. DeployHQ's zero downtime deployments work well with EmDash. Each deployment goes into a new directory, and a symlink switches to the new version atomically. Just make sure your DATABASE_PATH and any uploaded media point to a shared directory outside the release path so they persist across deployments.

Does EmDash work with DeployHQ's build pipeline caching?

The build pipeline caches node_modules between deployments, so subsequent builds are faster since npm only installs changed dependencies. Astro's build output isn't cached (it rebuilds each time), but the dependency caching alone can cut build times significantly.

Can I deploy EmDash to shared hosting via FTP?

EmDash requires a long-running Node.js process, which most shared hosting plans don't support. You need a VPS, cloud instance, or container hosting where you can run node dist/server/entry.mjs persistently. DeployHQ supports FTP and SFTP deployment protocols, but the server itself must support Node.js 22+.

How do I handle database migrations during deployment?

EmDash automatically runs migrations when the application starts (for SQLite, libSQL, and PostgreSQL). There's no separate migration step needed in your deployment pipeline. The restart via PM2 or systemd triggers the migration check on boot.

Can multiple team members deploy independently?

Yes. DeployHQ supports team collaboration with role-based permissions. You can restrict who can trigger deployments while giving everyone read access to deployment logs. Combined with DeployHQ's deployment approvals, you can require sign-off before production deployments go live.

Next Steps

You now have a production EmDash deployment powered by Git-based automation through DeployHQ. Every push to your repository triggers a clean build and deployment — no manual file transfers, no SSH-ing into servers to run commands.

From here, you might want to:

Set up deployment notifications to get Slack or email alerts on each deploy
Configure a staging server in DeployHQ to test changes before they hit production
Explore EmDash's plugin system to extend your CMS with custom functionality
Add a build pipeline step for running tests before deployment

Ready to automate your EmDash deployments? Sign up for DeployHQ and connect your repository in minutes.

If you have questions about deploying EmDash or any other framework with DeployHQ, reach out to us at support@deployhq.com or on Twitter/X @deployhq.

OpenClaw Skills: How to Find, Install, and Build Your Own

DeployHQ — Tue, 07 Apr 2026 06:13:28 +0000

If you followed our guide to deploying OpenClaw on a VPS, you've got a self-hosted AI assistant running on infrastructure you control. Out of the box it can chat, browse the web, run terminal commands, and remember context across sessions. Skills are what turn it from a capable chatbot into an automation engine that handles the repetitive parts of your workflow without being asked twice.

This post covers what Skills are, how to find and install them, a tour of the most useful directories, and how to build one from scratch to automate a real task. We'll also walk through troubleshooting common issues and best practices for writing skills that work reliably across environments.

What Are Skills?

A Skill is a directory containing a SKILL.md file — a Markdown document with YAML frontmatter — that teaches OpenClaw a repeatable procedure. When OpenClaw starts, it reads all eligible skills and injects compressed descriptions of them into its system prompt. The agent then knows which skills are available and invokes them automatically when a user request matches.

The simplest skill is just a natural-language runbook:

skills/
└── my-skill/
    └── SKILL.md

More advanced skills can include supporting scripts and configuration, but the SKILL.md is always the entry point. Unlike traditional plugins, which require the host application to define an API surface, Skills work by giving the LLM instructions — the model figures out how to use them in context.

Three locations are checked when loading skills, in precedence order:

<workspace>/skills — workspace-specific, highest priority
~/.openclaw/skills — user-level, shared across all agents on the machine
Built-in bundled skills — shipped with the install, lowest priority

This means you can override a bundled skill just by dropping a folder with the same name into your workspace directory.

flowchart LR
    A["Workspace Skills\n(./skills)"] -->|highest priority| D["OpenClaw\nSystem Prompt"]
    B["User-Level Skills\n(~/.openclaw/skills)"] -->|medium priority| D
    C["Bundled Skills\n(built-in)"] -->|lowest priority| D
    D --> E["Agent Ready\n— skills injected"]

Finding Skills: The ClawHub Registry

ClawHub is the official public skills registry, hosting over 13,700 community-built skills. Use the CLI to search and install:

# Search by keyword
clawhub search "github pull request"

# Install a skill
clawhub install pr-summary

# Update all installed skills
clawhub update --all

By default clawhub install places the skill in ./skills under your current directory. To install globally (visible to all your OpenClaw workspaces):

clawhub install pr-summary --global

The community has also published a curated list — awesome-openclaw-skills — which filters the registry down to 5,400+ vetted skills organised into categories. It's the faster way to browse if you don't already know what you're looking for.

Security note : Treat third-party skills as untrusted code. Read the SKILL.md before enabling a skill, especially if it requires API keys or system binaries. A skill that phones home with your environment variables is possible to write — the registry has moderation, but it's not a guarantee.

A Tour of the Skill Categories

Coding & Development (1,200+ skills) — the largest category by far. Highlights include skills for searching academic papers via OpenAlex, generating hash-chained audit logs for agent actions, and full GitHub workflow automation (open PRs, review diffs, triage issues). If your team uses GitHub-based deployment workflows, skills in this category can trigger deploys directly from a conversation — push a branch, open a PR, and let your CI pipeline handle the rest.

DevOps & Cloud (400+ skills) — Docker container management, process health monitoring, cloud provider CLIs. The agentic-devops skill handles common operations like restarting a crashed container or tailing logs from a service, triggered by a plain-language message. Teams running zero downtime deployments can pair these skills with health-check monitoring to automatically roll back a release if the new container fails readiness probes.

Browser & Automation (335 skills) — web scraping, UI testing, form automation. Useful for monitoring pages that don't expose APIs or automating login-gated workflows. A common pattern is combining a browser skill with a notification skill to alert you when a competitor changes their pricing page or when your own staging environment returns errors after a deploy.

Productivity & Tasks (200+ skills) — Notion CRUD, calendar management, email triage. The better-notion skill gives full create/read/update/delete access to Notion pages and databases from any messaging channel. Other standout skills in this category include time-tracking integrations that log hours against Jira tickets and daily digest generators that summarise activity across multiple project management tools.

Communication (149 skills) — Slack, Discord, Teams, and email integrations. Post to channels, summarise threads, draft replies. The Slack skills are particularly mature — you can configure them to post deployment summaries, standup reminders, or incident alerts directly into the relevant channel without leaving the OpenClaw conversation.

Git & GitHub (170 skills) — beyond the basics, there are skills for commit message generation, changelog drafting, and coordinating multi-repo releases. The release-coordinator skill is worth highlighting: it tags a release, generates a changelog from merged PRs, and posts the release notes to Slack in a single invocation.

Building Your Own Skill

The quickest way to understand Skills is to build one. Here's a practical example: a daily standup note generator that reads your recent git commits and drafts your standup update, so you never have to manually trawl through git log before your morning call.

Step 1 — Create the folder

mkdir -p ~/.openclaw/skills/standup-notes

Step 2 — Write the SKILL.md

nano ~/.openclaw/skills/standup-notes/SKILL.md


---
name: standup-notes
description: Generates a standup update from git commits in the last 24 hours across local repositories
user-invocable: true
metadata: {"openclaw":{"requires":{"bins":["git"]}}}
---

# Standup Notes Generator

When the user asks for standup notes, a standup summary, or "what did I work on yesterday", follow these steps:

## Steps

1. Ask the user which directory their repositories live in, or use `~/repos` as the default if they don't specify.

2. Find all git repositories in that directory:

bash
find ~/repos -maxdepth 2 -name ".git" -type d | sed 's|/.git||'


1. For each repository found, get commits from the last 24 hours authored by the current git user:

2. Collect all results. Ignore repos with no recent commits.

3. Group the commits by repository name and draft a standup update in this format:

4. Keep the language concise and past-tense. Replace jargon-heavy commit messages with plain descriptions where possible.

5. Output the draft in a code block so it's easy to copy.

## Example trigger phrases

- <q>Give me my standup notes</q>
- <q>What did I work on yesterday?</q>
- <q>Draft my standup for today</q>
- <q>Standup summary</q>```



### Step 3 — Test it

Restart the OpenClaw gateway to pick up the new skill:



```shell
openclaw gateway restart

Then send your bot a message:

Give me my standup notes

OpenClaw will run the git commands, collect the output, and return a formatted standup summary. Because the instructions are plain English, you can iterate on the output by replying — make it shorter or use first person — without editing the skill.

Step 4 — Extend it with an automatic post

Once the notes look right, extend the skill to post them directly to your team's Slack channel. Add a section to the SKILL.md:

## Posting to Slack (optional)

If the user asks to "post" or "send" the standup, use the Slack skill (if installed) to post the formatted message to the `#standup` channel. If the Slack skill is not available, output the message and tell the user to copy it manually.

Now the full workflow — generate, review, post — happens in one conversation turn.

Skill SKILL.md Reference

Here are the frontmatter fields you'll use most often:

Field	Type	Description
`name`	string	Unique identifier (used by clawhub)
`description`	string	One-line summary injected into the system prompt
`user-invocable`	boolean	Exposes the skill as a `/skill-name` slash command (default: `true`)
`disable-model-invocation`	boolean	Excludes the skill from model prompts — use for slash-command-only tools
`metadata`	JSON (single line)	Gating, emoji, OS requirements, installer specs

The metadata.openclaw.requires object gates the skill so it only loads when its dependencies are met:

---
name: my-tool
description: Does something with jq and an API key
metadata: {"openclaw":{"requires":{"bins":["jq","curl"],"env":["MY_API_KEY"]}}}
---

If jq isn't on PATH or MY_API_KEY isn't set, OpenClaw skips the skill entirely — it won't show up in the agent's prompt or the UI.

Tips for Writing Effective Skills

Writing a skill that works on your machine is straightforward. Writing one that works reliably across environments and for other users takes a bit more discipline.

Be explicit about prerequisites. Always declare required binaries and environment variables in the metadata.openclaw.requires block. A skill that silently fails because jq isn't installed wastes debugging time. If your skill needs a specific version of a tool, mention it in the instructions — the requires block only checks for presence, not version.

Write instructions for the model, not for humans. The LLM reads your SKILL.md, so phrase steps as direct commands rather than explanations. Run docker ps and parse the output is better than You might want to check which containers are running. Ambiguity in instructions leads to inconsistent behaviour across different models and context windows.

Keep descriptions short and specific. The description field is injected into the system prompt on every conversation. A verbose description eats tokens that could be used for reasoning. Aim for 10-15 words that clearly state what the skill does and when to use it.

Handle failure gracefully. Include instructions for what the agent should do when a command returns an error or produces unexpected output. If the API returns a 401, tell the user their token may have expired prevents the agent from guessing or hallucinating a recovery path.

Test with a clean environment. Before publishing, test your skill on a machine that doesn't have your personal dotfiles, aliases, or globally installed packages. What works in your shell might not work on a fresh Ubuntu server where the only tools available are what's declared in the skill's requirements.

Scope each skill to one task. A skill that tries to do everything — search, filter, format, post, and archive — is harder to maintain and more likely to confuse the model. Break complex workflows into smaller skills that compose together. The standup-notes example above delegates posting to the Slack skill rather than reimplementing Slack integration.

Troubleshooting Common Issues

Skill not appearing in the agent's prompt. The most common cause is a missing or malformed metadata.openclaw.requires block. If the skill requires a binary that isn't installed or an environment variable that isn't set, OpenClaw silently skips it. Run openclaw skills list to see which skills loaded and which were skipped, along with the reason.

Skill loads but doesn't trigger. Check the description field — if it's too vague, the model may not recognise when to invoke it. A description like Useful helper tool gives the LLM almost nothing to work with. Rewrite it to match the kind of phrases users actually say: Generates daily standup notes from recent git commits.

Permission denied errors. Skills that run shell commands inherit the permissions of the OpenClaw process. If you're running OpenClaw as a non-root user (which you should be), commands like systemctl restart nginx will fail. Either configure passwordless sudo for specific commands, or have the skill check permissions first and return a clear message instead of a raw error trace.

Dependency not found on remote servers. A skill that works locally may fail on your VPS because a binary (e.g., jq, gh, docker) isn't installed there. Add all system-level dependencies to your server provisioning script or Dockerfile. Declaring them in the skill's requires.bins block prevents the skill from loading at all, which is better than it loading and then crashing mid-execution.

Conflicting skills. If two skills have overlapping trigger patterns, the model may pick the wrong one. The easiest fix is to make the description fields more distinct. If both skills live in the same precedence tier (e.g., both in ~/.openclaw/skills), the one loaded first alphabetically wins — rename the folder to control order if needed.

Changes not taking effect after editing. OpenClaw reads skills at gateway startup. After editing a SKILL.md, you need to run openclaw gateway restart for the changes to take effect. Hot-reloading is on the roadmap but not yet implemented.

Publishing to ClawHub

When your skill works reliably and you want to share it:

# From the skills directory
clawhub publish ./standup-notes --slug standup-notes --version 1.0.0

Publishing requires a GitHub account at least a week old (abuse prevention). The registry runs automated checks for obviously malicious patterns, but passes it to you to write a clear README and document what environment variables the skill uses and why.

For updates, bump the version and republish:

clawhub publish ./standup-notes --slug standup-notes --version 1.1.0

Keeping Skills in Sync Across Servers with DeployHQ

If you're running OpenClaw on a VPS — or across multiple servers — keeping skills in sync manually is error-prone. The same Git-based approach from the VPS deployment guide applies here: store your custom skills in a repository and let an automated deployment platform push changes to every server automatically.

my-openclaw-config/
├── config.json
└── skills/
    ├── standup-notes/
    │ └── SKILL.md
    └── deploy-digest/
        └── SKILL.md

Set up Git deployment automation so that every push to your main branch triggers a deployment. Add a post-deployment command using build pipelines to copy the skills into place and restart the gateway:

rsync -av skills/ ~/.openclaw/skills/
openclaw gateway restart

Every time you add or update a skill and push to your repository, DeployHQ deploys it to all connected servers — no SSH sessions required. If a skill breaks something, use one-click rollback to revert to the previous working version from the dashboard.

For teams with larger budgets or multiple environments (staging, production), DeployHQ's pricing plans include multiple server targets per project — deploy to staging first, verify the skill works, then promote to production.

The Skills ecosystem is what makes OpenClaw genuinely composable. Start with a few skills from ClawHub, modify them to match your workflow, and build custom ones for the tasks that are specific to your team. The bar to entry is low — if you can write a clear step-by-step process in plain English, you can write a skill.

Sign up for DeployHQ to automate skill deployments across your VPS fleet, or drop us a line at support@deployhq.com if you have questions. Find us on Twitter at @deployhq.

SOC 2 Compliance for Deployment Workflows: What Auditors Look For

DeployHQ — Thu, 02 Apr 2026 17:38:52 +0000

Every tool in your deployment pipeline is now under scrutiny. If your team is pursuing SOC 2 Type II certification — or any compliance framework that governs how software changes reach production — your deployment workflow is no longer just DevOps. It's an audit surface.

This guide breaks down what SOC 2 auditors actually look for in deployment tooling, which controls matter most, and how to configure your pipeline so it passes muster without slowing your team down.

Why Your Deployment Pipeline Is an Audit Target

SOC 2's Trust Service Criteria (TSC) don't mention CI/CD or deployment tools by name. But several controls map directly to how code moves from a developer's machine to production:

CC6.1–CC6.2 (Logical Access): Who can trigger deployments? How are they authenticated?
CC6.3 (Role-Based Access): Can a junior developer deploy to production? Should they be able to?
CC7.1–CC7.2 (System Monitoring): Do you have immutable logs of every deployment — who, what, when, where?
CC8.1 (Change Management): Are production changes reviewed and approved before they go live?
CC9.2 (Vendor Risk): Does your deployment tool vendor meet SOC 2 requirements themselves?

The uncomfortable truth: 68% of SOC 2 qualified opinions (failures) stem from access control weaknesses in CC6.1–CC6.8. Your deployment tool is often the weakest link because it has direct write access to production servers.

The Six Controls Auditors Actually Check

1. Authentication: SSO and MFA

Auditors want to see that access to deployment tooling is consolidated through your identity provider (IdP). This means:

Single Sign-On (SSO) via SAML or OIDC — so access is governed by your IdP (Okta, Azure AD, Google Workspace), not a separate username/password
Multi-Factor Authentication (MFA) enforced at the organisation level, not optional per user
Centralised deprovisioning — when someone leaves the team, their deployment access is revoked automatically through the IdP, not manually by an admin who might forget

Why this matters : If your deployment tool uses standalone credentials, every audit cycle requires manual evidence that offboarded employees had their access revoked. SSO makes this automatic and auditable.

DeployHQ approach : DeployHQ supports team-based access control with configurable permissions per project and server group. For teams requiring SSO, DeployHQ integrates with enterprise identity providers to centralise authentication.

2. Role-Based Access Control (RBAC)

Not everyone who can view a project should be able to deploy to production. Auditors look for:

Separation of duties — developers can deploy to staging; only designated leads or automated pipelines deploy to production
Granular permissions — per-environment, per-server, per-action (view, deploy, configure)
Documented access policies — who has what access and why

flowchart LR
    A[Developer] -->|Can deploy| B[Staging]
    A -.->|Cannot deploy| C[Production]
    D[Team Lead] -->|Can deploy| B
    D -->|Can deploy| C
    E[CI Pipeline] -->|Auto-deploy| B
    E -->|Requires approval| C

DeployHQ approach : DeployHQ's permission system lets you assign roles per project — restricting who can deploy to which server groups. You can set up configurations where staging deploys happen automatically on push while production deploys require manual trigger from authorised users.

3. Immutable Audit Trails

Every deployment must produce a tamper-evident log entry containing:

Who triggered the deployment (authenticated identity, not just admin)
What was deployed (commit SHA, branch, changed files)
When the deployment occurred (timestamp)
Where it was deployed to (server, environment)
Whether it succeeded or failed
What changed — a diff or file manifest of what was actually transferred

These logs must be immutable — no one should be able to delete or modify deployment records after the fact.

DeployHQ approach : DeployHQ maintains a complete deployment history for every project, including the triggering user, commit reference, target servers, transferred files, and build output. This history is accessible via the dashboard and API for audit evidence collection.

4. Change Management and Approval Gates

SOC 2's CC8.1 requires that changes to production are authorised before they take effect. In practice, this means:

Branch protection rules — production deployments only from protected branches (e.g., main) that require pull request reviews
Manual approval gates — someone must explicitly approve production deploys, even if staging is automated
Emergency change procedures — a documented process for hotfixes that bypasses normal review, with after-the-fact review requirements

flowchart TD
    A[Code Push] --> B{Branch?}
    B -->|feature/*| C[Run Tests]
    C --> D[Deploy to Staging]
    B -->|main| E{PR Approved?}
    E -->|Yes| F[Deploy to Production]
    E -->|No| G[Block Deployment]
    F --> H[Log Deployment]
    D --> H

DeployHQ approach : DeployHQ supports conditional deployments — you can configure automatic deployments for staging branches while requiring manual triggers for production. Combined with your Git provider's branch protection, this creates a documented approval chain from code review to production deployment.

5. Environment Separation

Auditors verify that development, staging, and production environments are isolated:

Separate credentials — production server credentials are not shared with staging
Network isolation — staging cannot accidentally write to production databases
Independent configurations — environment variables, API keys, and secrets are managed per environment

DeployHQ approach : DeployHQ's server groups allow you to define separate deployment targets with independent credentials, paths, and configurations for each environment. Each server group has its own deployment history and access controls.

6. Vendor Compliance (Your Tools Are Part of Your Audit)

Under CC9.2, auditors assess the compliance posture of your third-party vendors. For deployment tools, this means:

Does the vendor have their own SOC 2 Type II report?
What data does the vendor access? (Server credentials, source code, environment variables)
How does the vendor store and protect sensitive data?
What happens if the vendor has a security incident?

What to ask your deployment tool vendor :

Do you have a current SOC 2 Type II report?
How are server credentials stored? (At rest encryption? Key management?)
Who at your organisation can access customer deployment configurations?
What's your incident response process?
Do you support data residency requirements?

Beyond SOC 2: Other Compliance Frameworks

SOC 2 isn't the only framework that cares about your deployment pipeline. Here's how the requirements map across frameworks:

Control	SOC 2	ISO 27001	HIPAA	PCI DSS
SSO/MFA	CC6.1–CC6.2	A.9.4.2	§164.312(d)	Req 8.3
RBAC	CC6.3	A.9.2.3	§164.312(a)(1)	Req 7.1
Audit trails	CC7.1–CC7.2	A.12.4.1	§164.312(b)	Req 10.1
Change management	CC8.1	A.14.2.2	§164.312(e)(1)	Req 6.4
Vendor management	CC9.2	A.15.1.1	§164.308(b)(1)	Req 12.8

The good news: if your deployment pipeline meets SOC 2 requirements, you're largely covered for these other frameworks too. The controls are complementary, not conflicting.

A Practical Compliance Checklist for Your Deployment Pipeline

Use this checklist to assess your current deployment workflow against SOC 2 requirements:

Authentication & Access

[] SSO enabled for all deployment tool access
[] MFA enforced at the organisation level (not optional)
[] Automated deprovisioning when team members leave
[] No shared credentials or service accounts used for interactive access

Permissions & Roles

[] Production deployment restricted to authorised roles
[] Staging and production use separate permission sets
[] Access reviews conducted quarterly (documented)
[] Principle of least privilege applied to all roles

Audit & Logging

[] Every deployment logged with user identity, commit, timestamp, and target
[] Deployment logs are immutable (cannot be deleted or modified)
[] Logs retained for the audit period (typically 12 months)
[] Failed deployments logged with error details

Change Management

[] Production deployments require prior approval (PR review or manual gate)
[] Emergency change process documented and followed
[] Rollback procedures documented and tested
[] All deployments traceable to a specific code change (commit SHA)

Environment Isolation

[] Separate credentials for each environment
[] Production configuration not accessible from staging
[] Environment-specific secrets management
[] Network segmentation between environments

Vendor Management

[] Deployment tool vendor has current SOC 2 Type II report
[] Vendor security review conducted annually
[] Data processing agreement (DPA) in place
[] Incident notification procedures agreed upon

Getting Started

If your team is beginning the SOC 2 journey, here's a practical order of operations:

Audit your current state — map out who has access to what, how deployments are triggered, and where the gaps are
Fix authentication first — SSO and MFA have the highest ROI because they address the most common audit failures
Enable audit logging — make sure every deployment is logged with enough detail for an auditor to reconstruct the event
Implement approval gates — start with production, then extend to other sensitive environments
Document everything — auditors care as much about documented policies as they do about technical controls

The goal isn't to make deployments slower. It's to make them provably secure — so that when an auditor asks who deployed this change and why?, you have a clear, automatic answer.

If you're evaluating how DeployHQ fits into your compliance workflow, you can explore our features or start a free trial to test the deployment controls against your audit requirements.

For questions about enterprise features including SSO, contact us at support@deployhq.com or reach out on X (@deployhq).

DEV Community: DeployHQ

Self-Host n8n on a VPS: Docker, HTTPS, and Git-Based Updates

What you'll build

Why self-host n8n at all?

Prerequisites

Step 1: Provision the VPS

Step 2: The n8n Docker Compose stack

Step 3: Put Nginx in front with Let's Encrypt

Step 4: First run

Step 5: Wire up Git-based deploys with DeployHQ

Step 6: Workflows as code

Step 7: Upgrade n8n safely

Step 8: Backups

Where to go from here

DeployHQ CLI: Deploy From Your Terminal (or Let Your AI Agent Do It)

Why a Terminal-First Deployment Tool Matters

Installing the DeployHQ CLI

Authenticating

Your First Deployment

Watching, Logs, and Rollback

Output Contract: Why It Matters for AI Agents

Wiring dhq Into Your AI Coding Assistant

Claude Code

Cursor

Codex CLI / Windsurf

Using dhq in CI/CD

Migrating From the Old Ruby Gem

Where to Go Next

New DeployHQ integrations: Linear, Google Chat, Telegram, and signed webhooks

Deploy status, posted back to GitHub, GitLab, and Bitbucket

A Linear Release for every deploy, automatically

Card-formatted alerts in Google Chat spaces

Telegram alerts for the on-call rotation

Signed HTTP webhooks for everything else

Where this fits

Deploy Hermes Agent on a VPS: DeployHQ Workflow + How It Differs from OpenClaw

What Hermes Agent does

Hermes Agent vs OpenClaw: when to pick which

Pre-flight checklist

Step 1 — Server hardening

Step 2 — Install Docker

Step 3 — Initial Hermes Agent install

Step 4 — Move configuration into Git

Step 5 — DeployHQ project setup

Step 6 — Persistent data (this is the one most people miss)

The agency multi-tenant pattern

Common gotchas

Where to go next

6 free GitHub repos that cut your Claude Code token bill

Cut your token bill

1. rtk — compress terminal output before it hits Claude

2. caveman — make Claude talk like a caveman

3. code-review-graph — let Claude read only what matters

4. agent-browser — stop re-authenticating every session

See where your tokens go

5. claude-usage — a local dashboard for tokens, costs, and history

6. claude-usage-monitor — real-time terminal predictions

How these stack

A word on the $100/mo claim

PR Radar vs GitHub Notifications vs Email: How Developers Actually Track Pull Requests

The five options on the table

Option 1: Email — the default everyone ignores

Option 2: GitHub's notification inbox

Option 3: Slack integrations

Option 4: Refined GitHub and Notifier for GitHub

Option 5: PR Radar

Side-by-side

The deployment connection

Who should pick which

Try it

Mailtrap vs SendGrid vs Mailgun: Best Email API for Node.js in 2026

Quick Comparison Overview

Installation and Setup Comparison

Mailtrap

Mailgun

SendGrid

Deliverability and Infrastructure

Mailtrap

Mailgun

SendGrid

Wiring `dhq` Into Your AI Coding Assistant

Using `dhq` in CI/CD