DEV Community: DeployHQ

DeployHQ Managed VPS vs Render: Real Linux vs PaaS Sandbox

DeployHQ — Mon, 13 Jul 2026 08:49:34 +0000

DeployHQ Managed VPS and Render solve the same problem — get an app from a Git repository to a running production service — but they take opposite architectural bets. Render is fully managed PaaS: containers, autoscaling, managed databases, zero infrastructure decisions. DeployHQ Managed VPS is a real Linux box with full SSH access plus the deployment pipeline wired in.

The right choice depends on whether your workload needs real Linux (custom services, SSH access, anything outside a PaaS sandbox) or whether the PaaS abstraction's constraints are actually freedoms — fewer decisions to make, less operational surface to maintain.

This guide is a head-to-head comparison: features, pricing, lock-in, and when each one wins. (For broader Heroku-replacement framing — Render alongside Railway and Fly.io — our Heroku alternatives in 2026 roundup covers the wider migration story.)

TL;DR

If your application fits a PaaS shape — stateless web service, managed Postgres, autoscaling on CPU thresholds, no need to SSH into the box — Render is the cleaner answer. The PaaS model removes a meaningful amount of operational work, and Render's product surface is mature and well-designed.

If you need a real Linux box — for SSH access, custom services, cron jobs, third-party agents (monitoring, log shipping, backups), or any workload that needs to step outside a sandbox — DeployHQ Managed VPS is the right product. You get a real Ubuntu VPS plus the DeployHQ deployment pipeline already wrapped around it.

For broader context, our roundup of the best software deployment tools in 2026 places Render, DeployHQ, and the rest of the category side by side.

At a glance: feature comparison

Capability	DeployHQ Managed VPS	Render
Architectural model	Linux VPS + deployment pipeline	PaaS containers + managed services
Root SSH access	Yes	No (PaaS sandbox)
Custom services / cron / daemons	Yes (it's a real Linux box)	Cron jobs supported; custom binaries limited
Underlying infrastructure	DigitalOcean	AWS / GCP
Server sizes	1-2 vCPU / 1-4 GB (beta)	Container instances (Starter, Standard, Pro tiers)
Autoscaling	No (manual sizing)	Yes (CPU / memory thresholds)
Managed databases bundled	No (run your own or use external)	Yes (managed Postgres, Redis)
Build pipeline	DeployHQ generic pipeline	Render native build
Deploy other targets in same project	Yes (VPS, static, shared, S3)	No (Render-only)
One bill with deployment tool	Yes	Yes (Render bundles both)
Beta status	Yes (mid-2026)	GA
Vendor lock-in	Low (it's just Linux + SSH)	Medium-high (PaaS runtime + service bindings)

Real Linux on one side. PaaS sandbox on the other.

When DeployHQ Managed VPS is the right choice

You need SSH access to a real Linux box. This is the structural differentiator and it's where most I can't use Render for this decisions land. If your app needs to install system packages, run a background worker outside Render's supported types, set up a custom cron schedule with unusual semantics, run a third-party monitoring or log-shipping agent, or debug live with strace / tcpdump / journalctl, PaaS locks you out. DeployHQ Managed VPS gives you root over SSH and you do whatever Linux lets you do. The Managed VPS pillar guide walks through what you get out of the box.

You want a generic deployment pipeline that ships to many targets. Render's build-and-deploy is specific to Render — it builds, runs, and serves your code on Render. DeployHQ's pipeline ships any artifact to any target — Managed VPS, your own Hetzner box, DigitalOcean Droplets, shared hosting, S3 buckets, DeployHQ Static Hosting. If your project has any non-PaaS-shaped component (a worker that needs root, a static frontend you want on a separate edge, a service that has to live on shared hosting because compliance), DeployHQ handles all of it. Render handles the Render-shaped part.

You don't want PaaS lock-in on your runtime. Render's value-adds — managed Postgres bound to the app, autoscaling on dedicated tiers, the Render runtime conventions — are tightly coupled to staying on Render. If you outgrow Render's constraints or pricing, migration means re-architecting around a different runtime. DeployHQ Managed VPS runs stock Linux — your app already works anywhere Linux runs.

You want to mix targets in one project. A real example: production web on Managed VPS, background jobs on a separate Managed VPS or BYO VPS, static frontend on Static Hosting, all in one DeployHQ project with one billing relationship. Render can't host the static frontend at scale (Render Static Sites exists but lives in the Render ecosystem) and can't deploy to non-Render targets. DeployHQ handles all of it from one project.

When Render is the right choice

You don't want to manage Linux at all. Render is genuine PaaS — no OS to patch, no security updates to apply, no system packages to manage. If I don't want to think about the box, I just want to push code describes your team, Render delivers that cleanly. DeployHQ Managed VPS is less operational work than a raw VPS, but it's still a Linux box; if you'd rather not have that surface, Render's abstraction is what you want.

You need autoscaling. Render's dedicated tiers offer autoscaling on CPU and memory thresholds. DeployHQ Managed VPS is manually sized — pick a tier, resize as needed. If your workload spikes unpredictably and you want the platform to absorb it without intervention, Render is the right answer.

You want managed databases bundled in. Render offers managed Postgres and Redis with private networking, automatic backups, point-in-time recovery, and bindings into your app. DeployHQ Managed VPS doesn't bundle a database — you'd run Postgres yourself on the VPS (fine for many workloads), use a separate managed service (Neon, Supabase, DigitalOcean Managed Databases), or self-host in a separate VPS.

Your workload genuinely fits the PaaS shape. Stateless web service, reads from a managed database, writes to object storage — the canonical PaaS shape. If that describes your app and you don't need to step outside it, Render's constraints aren't really constraints. The simplicity is a feature.

Pricing: side by side

As of June 2026 — check vendor pages for current numbers.

Render offers a Free tier (with limitations: services sleep after idle, build minute caps, single concurrent build), then paid web service tiers starting from a Starter price point and scaling up to dedicated instances with autoscaling. Managed Postgres starts free with row limits and scales up with paid tiers offering increased storage and high availability. The current exact tier pricing is best checked directly on render.com — Render adjusts pricing periodically and a stale number here is worse than no number.

What's worth noting structurally: Render's pricing scales with usage in a few dimensions — instance size, instance count (for autoscaling), database tier, bandwidth, and additional service slots. For a single small web service plus a small database, Render is competitive with other PaaS options. For larger workloads with several services and a HA database, the bill can scale quickly.

DeployHQ Managed VPS charges a fixed monthly rate per server, shown on the provisioning form in your account's currency. Server sizes are currently 1 vCPU / 1 GB up to 2 vCPU / 4 GB in the beta. Pricing rolls into your DeployHQ plan on a single monthly invoice. Trial accounts can provision one Managed VPS at the smallest size at no charge.

The honest framing: a single small Render web service plus a small managed DB can be cheaper than DeployHQ Managed VPS plus a separately hosted Postgres if you only have one app. The math tilts toward DeployHQ when you have multiple deployment targets (one project deploying to multiple servers) or you're already paying for DeployHQ to deploy code elsewhere. Compare current DeployHQ pricing for the full breakdown.

Moving between them (it's not all-or-nothing)

Different architectural models means migration involves real work in either direction — not just DNS swaps.

From Render to DeployHQ Managed VPS: provision the VPS in DeployHQ, install your app's runtime (Node, Ruby, Python, Go — whatever Render was running), set up your service supervisor (systemd, PM2, Passenger), migrate your managed Postgres data to either a self-hosted Postgres on the same VPS or a separate managed-DB provider, and configure DeployHQ's pipeline to handle build + deploy. If Render was handling autoscaling for you, you'll either manually size the VPS for peak load or move to a different scaling model (load balancer + multiple VPS instances). The migrating to DeployHQ guide covers the broader migration pattern.

From DeployHQ Managed VPS to Render: re-architect around Render's runtime conventions. Define your render.yaml service spec, set up managed-DB bindings, adapt any custom services to Render-supported types. If your app used SSH-only operations (cron jobs with unusual semantics, custom binary execution, monitoring agents), find PaaS-compatible alternatives. This is harder in practice than the other direction because you're moving toward a more constrained runtime.

Or: combine them. Run web tier on Render for autoscaling and managed DB, run worker processes or background jobs on a DeployHQ Managed VPS where you can install whatever you need, and keep both in one DeployHQ project for unified deployment of the worker side. This combines the autoscaling story (Render) with the real-Linux story (DeployHQ Managed VPS) — both architectures get used for what they're good at.

If you're stepping up from shared hosting and weighing modern deployment options generally, 5 signs it's time to upgrade from shared hosting to automated deployments covers the inflection points.

The real Linux vs PaaS trade-off

Both products solve the deployment problem. They solve it for different application shapes.

Render is excellent for canonical PaaS workloads — stateless web services, standard runtimes, managed databases. It removes operational work in exchange for runtime constraints. Most CRUD apps fit this shape comfortably.
DeployHQ Managed VPS is excellent when the PaaS shape doesn't fit — when you need root access, custom services, third-party agents, or any workload that needs to step outside a sandbox. It's a real Linux box with deployment automation wrapped around it.

The honest answer for many teams is both. Run the canonical web tier on Render for the autoscaling and managed-DB ergonomics. Run the worker/cron/agent side on a Managed VPS where you can do whatever Linux lets you do. Use DeployHQ as the unifying deployment surface for whatever you put on the VPS side. The application splits along architectural lines instead of along vendor lines.

For Express / Node service deployments specifically, both platforms handle Node well — the choice comes down to whether you want the runtime managed for you or you want SSH into the box.

For the wider catalog of where Managed VPS fits with other DeployHQ hosting options, the hosting hub covers all five hosting types.

FAQ

Does DeployHQ Managed VPS allow SSH access like a regular VPS?Yes. It's a real Linux VPS. SSH in with the key DeployHQ generates (or your own key), install what you want, run any service. DeployHQ's deployment pipeline handles the build-and-deploy automation but doesn't restrict what runs on the box.

Does Render allow SSH access? No. Render is PaaS — you interact with the platform through its dashboard, CLI, and API. SSH into a running container isn't supported. This is by design — it's what makes the PaaS abstraction work.

Can I run a Laravel deployment on DeployHQ Managed VPS?Yes. PHP-FPM, Nginx, Composer, queue workers via Supervisor, Laravel scheduler via cron — all standard Linux setup. DeployHQ handles the build (Composer install, migrations, asset compilation), the VPS handles the runtime.

What about managed Postgres on DeployHQ Managed VPS?Not bundled. For small workloads, install Postgres on the VPS itself. For HA / point-in-time recovery / managed backups, point at a separate managed-DB service. DigitalOcean Managed Databases pairs well since the VPS is already on DO.

Is there a free tier on DeployHQ Managed VPS?Trial accounts can provision one Managed VPS at the smallest size at no charge. Custom SSH keys aren't available on trial; DeployHQ generates and uses a managed key automatically. Render has a free web service tier (with idle-sleep limitations) and free DB tier — both are useful for evaluation but typically not for production.

Get started

If you're already on DeployHQ, enable beta features under Settings > Beta Features and add a Managed VPS server to any project. The one-click rollback feature works on Managed VPS the same way it works on a BYO server.

If you're new, start a free trial and the included Managed VPS lets you ship a real project end-to-end before committing. For the wider picture of how Managed VPS fits with the other hosting options DeployHQ supports, see your universal deployment and hosting platform.

Render and DeployHQ Managed VPS are both good products in their lanes. Render wins when your workload fits PaaS. DeployHQ Managed VPS wins when it doesn't — or when you want real Linux for any reason. The split is structural, not feature-level; pick the architecture, not the feature list.

For more detail on the Managed VPS product, the Managed VPS support library has the full provisioning, lifecycle, and management documentation.

Questions or feedback on Managed VPS vs Render? Email support@deployhq.com or follow @deployhq on X for product updates.

Using Claude Code with SQLite: The Safest Way to Prototype Queries Locally

DeployHQ — Mon, 13 Jul 2026 08:49:24 +0000

Most guides about connecting an AI coding assistant to a database start with the hard case: a production Postgres cluster, credentials, network access, read-only roles. That is exactly backwards. If you are just getting comfortable with letting an assistant explore a schema and draft SQL for you, the smartest place to start is the database that lives entirely inside a single file on your laptop.

SQLite is that database. There is no server to run, no port to open, no user to grant. The whole thing is one .sqlite file you can open, copy, delete, and restore in seconds. That makes it the ideal sandbox for AI-assisted database work — a place where a bad query or a botched schema change costs you nothing, because rolling back is as simple as copying a file back over another one.

This post walks through pointing Claude Code at a local SQLite file, why a file-based database is the safest experimentation surface you can give an AI assistant, and how to prototype real queries before promoting anything to a server.

Why SQLite is the right place to start

Every other database engine assumes infrastructure. PostgreSQL and MySQL run as long-lived server processes, listen on a network port, and gate access behind users and roles. That is the correct model for production — but it is a lot of moving parts to stand up just to experiment with an AI assistant.

SQLite removes all of it. A SQLite database is a single ordinary file. Your application (or your assistant's tooling) opens the file directly and reads and writes rows in place. There is no daemon, no localhost:5432, no authentication handshake. If you have ever seen a .db or .sqlite file in a project, you have already been using it.

For AI-assisted work, three properties matter:

It is trivially reproducible. Delete the file, run your seed script, and you are back to a known state. No DROP DATABASE, no re-provisioning.
It is completely local. Nothing leaves your machine. There is no risk of an assistant accidentally touching shared staging data because there is no shared anything.
It is disposable by design. A SQLite file is meant to be copied, moved, and thrown away. That disposability is what turns it into a safe playground.

If you want the deeper trade-offs between the engines, the SQLite vs PostgreSQL vs MySQL comparison covers when each one earns its place. For learning the AI workflow, SQLite wins on setup cost alone.

Pointing Claude Code at a `.sqlite` file

Claude Code talks to databases through an MCP server — a small bridge process that exposes your database to the assistant as a set of tools. If the term is new, the complete guide to MCP servers explains what they are and why they matter. The one we use here is DBHub, and the full multi-engine setup lives in the step-by-step guide to querying databases with Claude Code and DBHub — this post won't re-run that whole setup, just the SQLite-specific piece.

DBHub supports SQLite directly, and the SQLite DSN is refreshingly short. Where Postgres needs a host, port, user, password, and database name, SQLite needs a path to a file:

sqlite:///./mydb.sqlite

That is the entire connection string. The sqlite:// scheme followed by a path — three slashes for a relative path, four for an absolute one like sqlite:////Users/you/data/mydb.sqlite.

In your Claude Code MCP configuration, DBHub takes that DSN as its --dsn argument:

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport", "stdio",
        "--dsn", "sqlite:///./mydb.sqlite"
      ]
    }
  }
}

Restart Claude Code, and it can now see your SQLite file's tables and columns. If you don't have a database to point at yet, DBHub also ships a demo mode that spins up an in-memory SQLite database, so you can kick the tires before pointing it at anything of your own. Keeping the exact DBHub flags handy is easier with the Claude Code cheatsheet open in another tab.

Why a file is the safest sandbox you can give an AI

Here is the property that makes SQLite genuinely different for AI-assisted work, not just easier to set up: your entire database is one file, so a complete backup is one copy command.

cp mydb.sqlite mydb.backup.sqlite

That single line is your rollback plan. Before you let the assistant run anything destructive — an ALTER TABLE, a bulk UPDATE, a schema rewrite it suggested — you copy the file. If the change goes sideways, you restore it:

cp mydb.backup.sqlite mydb.sqlite

You are back exactly where you started, byte for byte. There is no migration to reverse, no pg_restore, no hope the transaction rolled back cleanly. The safety net is the filesystem itself.

This changes how you can work with an assistant. On a shared server you approach every write cautiously, because a mistake affects other people and is annoying to undo. Against a copied SQLite file, you can be reckless on purpose: let the assistant try an aggressive denormalization, ask it to rewrite five tables, tell it to backfill a column three different ways and compare. Every experiment starts from a fresh copy and ends with a cp if it didn't pan out.

Prototype fearlessly, then promote deliberately. The whole point of a disposable local database is that undo is free — so use it to move fast locally, and save the careful, reviewed process for the moment your changes touch a real server. Start free with DeployHQ when you're ready to put a proper deployment pipeline behind those changes.

A good habit is one backup per experiment: copy the file, name the copy after what you're about to try (mydb.pre-index-test.sqlite), and keep the ones that produced results worth revisiting. Disk is cheap; a lost afternoon of exploration isn't.

Exploring schema and prototyping queries

With the file connected and a backup in your pocket, the workflow becomes conversational. Instead of memorizing table names, you ask.

Start by mapping the territory. Ask the assistant to describe the schema — tables, columns, types, foreign keys. Because DBHub exposes the structure as tools, Claude Code reads it directly rather than guessing, so what it tells you reflects the actual file, not a hallucinated model of it.

Then prototype against real shape. Describe what you want in plain English — show me the ten customers with the most orders in the last quarter — and let the assistant draft the SQL. Run it, read the result, and refine. Because you're working on a copy, you can run the query, realize the join is wrong, and iterate without any consequence beyond a few seconds.

Test schema changes the same way. Ask for an index, a new column, or a normalized table split, apply it to your working copy, and check whether queries behave the way you expected. If the change made things worse, restore the backup and try a different shape. This tight loop — propose, apply, inspect, keep-or-revert — is the core value of a disposable database.

A few practices keep the exploration honest:

Read the SQL before you run it. The assistant is drafting, not deciding. Skim every statement, especially anything that writes.
Back up before writes, not before reads. Selects can't hurt the file; UPDATE, DELETE, and ALTER can.
Seed deterministically. Keep a small script that rebuilds your test data so start over is always available.

The moment you point an assistant at a networked, multi-user database instead of a local file, that cp safety net disappears — which is exactly when you want to lock the connection down. Our guide to read-only guardrails for AI database access covers the dedicated-role and MCP-flag recipe that keeps a shared database as safe as a throwaway file.

When to graduate from SQLite

SQLite is a superb sandbox and a perfectly good production database for plenty of workloads — but there is a point where you outgrow it. Move to PostgreSQL or MySQL when you need real concurrency (many clients writing at once), network access from multiple application servers, or engine-specific features SQLite doesn't offer. The comparison linked earlier lays out exactly where each of those lines sits.

The reassuring part: the workflow you just learned transfers cleanly. Pointing Claude Code at Postgres or MySQL through DBHub is the same pattern, only the DSN changes from a file path to a host, port, and credentials (and MySQL adds a few connection quirks of its own). What you can't carry over is the cp-based safety net — which is precisely why doing your schema and query experimentation on SQLite first is worth it. You work out the shape where mistakes are free, and only take the validated result to an engine where they aren't.

Moving validated queries into a real deployment

Once a schema change or a set of queries has proven itself against your local file, it needs a disciplined path to production — because on a live database, the free-rollback luxury is gone. That is where the process flips from experiment freely to change carefully.

The safe pattern is to capture the validated change as a versioned migration and apply it as part of your deployment, not by hand. Our guide on how to handle database changes during a deployment covers version-controlling schema changes and running them automatically, and the deeper database migration strategies for zero-downtime deployments walks through applying those changes without taking the application offline.

DeployHQ fits at exactly this handoff. A build pipeline can run your migration step as part of every deploy, so the schema change you prototyped locally on SQLite ships the same way your code does — reviewed, versioned, and repeatable — instead of someone SSHing in to run SQL by hand. The local file gave you a place to be fearless; the pipeline gives you a place to be careful.

That is the arc of AI-assisted database work done well: experiment where undo is free, promote where it isn't, and never confuse the two. SQLite is where you start precisely because it makes the first half of that sentence effortless.

Ready to put a proper deployment pipeline behind your validated schema changes? Explore automated deployment for your stack and run your migrations automatically on every deploy.

Questions or feedback? Reach us at support@deployhq.com or on X at @deployhq.

Running AI Coding Agents in CI/CD: Claude Code, Codex, and Gemini CLI in Headless Mode

DeployHQ — Fri, 10 Jul 2026 14:47:36 +0000

This is Part 10 of our series on AI coding assistants for developers. See also: Agentic Workflows Explained and Comparing AI CLI Coding Assistants.

GitHub's Copilot Coding Agent is convenient — assign an issue and it opens a PR. But it's a black box. You don't choose the model, you can't add custom tools, and you're locked into GitHub's pricing and rate limits.

There's another way: run the same AI coding CLIs you use locally — Claude Code, Codex CLI, and Gemini CLI — as headless steps in your CI/CD pipeline. You control the prompt, the model, the tools, and the cost. The agent runs non-interactively, produces output, and the pipeline decides what to do with it.

This is the bring your own agent approach. It works on any CI platform that can run a shell command.

Headless Mode for Each CLI

Each tool has a way to run without interactive input — no terminal UI, no approval prompts, just input and output.

Claude Code

# Print mode — runs a single prompt, outputs result, exits
claude -p "Analyze the git diff and generate a changelog entry" \
  --allowedTools Edit,Write,Bash \
  --output-format json

# With stdin piping
git diff HEAD~1 | claude -p "Generate a changelog entry for these changes" \
  --output-format text

# With max tokens to control cost
claude -p "Fix the failing test in tests/auth.test.ts" \
  --allowedTools Edit,Read,Bash \
  --max-turns 10

Key flags: -p (print mode, non-interactive), --allowedTools (restrict what the agent can do), --output-format (json or text), --max-turns (limit iterations).

Codex CLI

# Full auto mode — no human approval needed
codex --approval-mode full-auto \
  --quiet \
  "Update the README with the latest API changes"

# With file restrictions
codex --approval-mode full-auto \
  --quiet \
  --full-auto-error-mode ask-user \
  "Add input validation to the user registration endpoint"

Key flags: --approval-mode full-auto (no interactive prompts), --quiet (minimal output).

Gemini CLI

# Non-interactive with prompt
echo "Generate unit tests for src/utils/validator.ts" | gemini

# With sandbox mode
gemini -s "Review the last commit for security issues" \
  --sandbox

Practical Use Cases with Full CI Config

1. Auto-Generate Changelog from Git Diff

The agent reads the diff since the last release tag and writes a human-readable changelog entry:

name: Generate Changelog

on:
  push:
    tags: ['v*']

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate changelog entry
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
          DIFF=$(git log ${PREV_TAG}..HEAD --oneline --no-merges)

          echo "$DIFF" | claude -p "Generate a changelog entry in Keep a Changelog format. Group changes into Added, Changed, Fixed, Removed. Be concise — one line per change. Output only the changelog markdown, nothing else." \
            --output-format text > CHANGELOG_ENTRY.md

      - name: Create release with changelog
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release create ${{ github.ref_name }} \
            --title "${{ github.ref_name }}" \
            --notes-file CHANGELOG_ENTRY.md

2. AI-Powered Code Review on Changed Files

Run the agent as a review step on every PR — it reads the diff and leaves comments:

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(gh pr diff ${{ github.event.pull_request.number }})

          REVIEW=$(echo "$DIFF" | claude -p "Review this diff for:
          1. Security issues (SQL injection, XSS, hardcoded secrets)
          2. Missing error handling
          3. Performance concerns (N+1 queries, unnecessary loops)
          4. Missing input validation

          Format as a markdown list. If no issues found, say 'No issues found.' Be specific — reference file names and line numbers." \
            --output-format text \
            --max-turns 3)

          gh pr comment ${{ github.event.pull_request.number }} \
            --body "## AI Code Review

          $REVIEW

          ---
          *Automated review by Claude Code. This is advisory — human review is still required.*"

Once an agent produces a change that passes review, the last mile is shipping it. Wire your CI into an automated build pipeline and a green run deploys to your own server automatically — the agent writes, CI validates, and the release goes out with no manual step in between.

3. Auto-Fix CI Failures

When tests fail, the agent reads the error output and proposes a fix:

name: Tests with Auto-Fix

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - name: Run tests
        id: tests
        continue-on-error: true
        run: npm test 2>&1 | tee test-output.txt

      - name: AI fix attempt
        if: steps.tests.outcome == 'failure'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code

          claude -p "The tests failed. Here's the output:

          $(cat test-output.txt)

          Read the failing test files and the source code they test.
          Fix the source code to make the tests pass.
          Do NOT modify the test files — fix the implementation." \
            --allowedTools Read,Edit,Bash \
            --max-turns 15

      - name: Verify fix
        if: steps.tests.outcome == 'failure'
        run: npm test

      - name: Commit fix
        if: steps.tests.outcome == 'failure'
        run: |
          git config user.name "AI Agent"
          git config user.email "ai-agent@deployhq.com"
          git add -A
          git diff --staged --quiet || git commit -m "fix: auto-fix failing tests (AI-generated)"
          git push

4. Security Scanning with AI Triage

Run a SAST tool, then have the AI prioritize and explain findings:

name: Security Scan + AI Triage

on:
  pull_request:

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Semgrep
        run: |
          pip install semgrep
          semgrep --config auto --json --output semgrep-results.json . || true

      - name: AI triage
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code

          TRIAGE=$(claude -p "Here are Semgrep security scan results:

          $(cat semgrep-results.json)

          Triage these findings:
          1. Remove false positives (explain why)
          2. Rank remaining issues by severity (Critical, High, Medium, Low)
          3. For each real issue, explain the attack vector in one sentence
          4. Suggest a fix for Critical and High issues

          Format as a markdown table." \
            --output-format text \
            --max-turns 3)

          echo "$TRIAGE" >> $GITHUB_STEP_SUMMARY

5. Generate Tests for Modified Code

When a PR changes source files, the agent generates missing tests:

name: Auto-Generate Tests

on:
  pull_request:

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate tests for changed files
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          CHANGED=$(gh pr diff ${{ github.event.pull_request.number }} --name-only | grep -E '\.(ts|js)$' | grep -v test | grep -v spec)

          for FILE in $CHANGED; do
            TEST_FILE=$(echo "$FILE" | sed 's/\.ts$/.test.ts/' | sed 's|src/|tests/unit/|')

            if [! -f "$TEST_FILE"]; then
              claude -p "Read $FILE and generate a comprehensive unit test file.
              Use Vitest. Follow the existing test patterns in the project.
              Save the test file to $TEST_FILE.
              Test all exported functions including edge cases." \
                --allowedTools Read,Write \
                --max-turns 10
            fi
          done

      - name: Verify tests pass
        run: npm test

      - name: Commit generated tests
        run: |
          git config user.name "AI Agent"
          git config user.email "ai-agent@deployhq.com"
          git add tests/
          git diff --staged --quiet || git commit -m "test: add AI-generated tests for new code"
          git push

Other CI Platforms

The same patterns work on any CI platform:

GitLab CI:

ai-review:
  stage: review
  image: node:20
  script:
    - npm install -g @anthropic-ai/claude-code
    - git diff origin/main...HEAD | claude -p "Review this diff for bugs and security issues" --output-format text > review.md
    - cat review.md
  artifacts:
    reports:
      dotenv: review.md
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Bitbucket Pipelines:

pipelines:
  pull-requests:
    '**':
      - step:
          name: AI Code Review
          image: node:20
          script:
            - npm install -g @anthropic-ai/claude-code
            - git diff origin/main...HEAD | claude -p "Review for security issues" --output-format text

Connecting to Deployment

After the agent's changes pass CI, you can trigger a deployment automatically using the DeployHQ CLI:

- name: Deploy to Staging
  if: success()
  run: |
    curl -fsSL https://www.deployhq.com/install-cli.sh | bash
    dhq auth login --token "${{ secrets.DEPLOYHQ_API_KEY }}"
    dhq deploy --server staging --wait --json

This completes the loop: agent writes code → CI validates → agent fixes failures → the deployment pipeline ships it. The full pattern is covered in our companion post on connecting agentic CI/CD to DeployHQ.

Cost Management

Running AI agents in CI can get expensive fast. Here's how to keep costs under control:

Strategy	How	Savings
Limit turns	`--max-turns 10`	Prevents infinite loops
Restrict tools	`--allowedTools Read,Edit`	Fewer API calls per turn
Filter triggers	Only run on `src/` changes	Skip docs-only PRs
Use cheaper models	Claude Haiku for simple tasks	10x cheaper than Opus
Cache results	Skip review if diff unchanged	Eliminates duplicate runs
Set timeouts	`timeout-minutes: 10`	Hard stop on runaway agents

A typical AI review step costs $0.02-0.10 per PR with Claude Sonnet. Auto-fix attempts cost more ($0.20-1.00) because the agent reads files and makes multiple edits. Budget accordingly — for most teams, this is cheaper than the developer time it saves.

Security Considerations

Running an AI agent in CI means giving it access to your code and (potentially) your secrets. Lock it down:

Scope secrets tightly. The agent needs an API key for its model provider. It does NOT need your database credentials, deployment tokens, or SSH keys. Use GitHub's environment-level secrets to control access.
Restrict file access. Use --allowedTools to prevent the agent from running arbitrary shell commands. Read,Edit is sufficient for most review tasks.
Validate output. Don't blindly commit agent-generated changes. Run your full test suite after any agent modification.
Audit agent commits. Tag agent-generated commits with a machine author (ai-agent@yourcompany.com) so they're easy to identify in git history.
Don't run agents on forks. Disable AI review steps on PRs from forked repositories — the fork author could craft a prompt injection in the diff.

When to Use What

Approach	Best For	Trade-offs
Platform agent (Copilot)	Issue-to-PR automation, managed infrastructure	Less control, GitHub-only, opaque
Headless CLI (Claude/Codex/Gemini)	Custom review, fix, and generation workflows	More setup, you manage costs, any CI platform
Dedicated review tool (CodeRabbit)	PR review specifically	Best review UX, less flexible for other tasks
No agent	Simple projects, strict security requirements	Maximum control, minimum risk

Most teams end up combining approaches: a dedicated review tool (CodeRabbit or Copilot) for every PR, plus headless CLI agents for specific workflows like changelog generation or test scaffolding.

Running your own AI agent in CI gives you control that platform-managed agents can't match. You choose the model, the prompt, the tools, and the budget. The trade-off is setup and maintenance — but once the workflow YAML is written, it runs on every PR without intervention.

Start with one workflow — changelog generation or AI code review — and expand from there. Keep costs visible, scope permissions tightly, and always run tests after agent modifications.

Ready to connect your AI-powered CI pipeline to deployment? DeployHQ deploys to any server you own with zero-downtime deployments, one-click rollback, and a CLI built for CI/CD automation. Get started for free.

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

Managing Secrets: .env Files, .env.example, and Config in DeployHQ

DeployHQ — Wed, 08 Jul 2026 07:18:27 +0000

Every application needs configuration that changes between environments — database URLs, API keys, feature flags. The .env file is the standard way to manage these values locally without hardcoding them into your source code. This guide explains what .env files are, how they work across languages, and how to handle them safely from development through deployment.

What Is a .env File?

A .env file is a plain text file that sits in the root of your project and stores configuration as key-value pairs:

DATABASE_URL=postgres://localhost:5432/myapp
API_KEY=sk-abc123def456
DEBUG=true
PORT=3000

Your application reads this file at startup and loads the values into the process environment. This keeps sensitive credentials and environment-specific settings out of your codebase.

The name .env follows the Unix convention where dot-prefixed files are hidden by default — present but unobtrusive.

The KEY=VALUE Format

The syntax is simple, but there are rules worth knowing:

# This is a comment
DATABASE_URL=postgres://localhost:5432/myapp

# Quoted values preserve whitespace
APP_NAME="My Application"

# Single quotes prevent variable expansion
GREETING='Hello $USER'

# No spaces around the equals sign
CORRECT=value
# WRONG = value <-- this breaks most parsers

Key rules:

No spaces around =. KEY=value is correct; KEY = value breaks most parsers
Comments start with # at the beginning of a line
Empty lines are ignored
Quotes are optional for simple values. Use double quotes for values with spaces, single quotes to prevent variable interpolation
No export keyword. Unlike shell scripts, .env files omit export. Some parsers accept it, but it's not standard

How Different Frameworks Load .env Files

The .env file doesn't load itself. Your language or framework needs a library to read it and inject values into the process environment.

Node.js

The dotenv package is the standard:

npm install dotenv


require('dotenv').config();

const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;

Node.js 20.6+ has a built-in --env-file flag that eliminates the package entirely:

node --env-file=.env app.js

Python

pip install python-dotenv


from dotenv import load_dotenv
import os

load_dotenv()

db_url = os.getenv("DATABASE_URL")
debug = os.getenv("DEBUG", "false").lower() == "true"

Django projects often use django-environ for typed access:

import environ
env = environ.Env()
environ.Env.read_env()

DEBUG = env.bool("DEBUG", default=False)
DATABASE_URL = env.db()

Ruby

# Gemfile
gem 'dotenv', groups: [:development, :test]

# Load early in boot
require 'dotenv/load'

db_url = ENV['DATABASE_URL']

Rails projects use dotenv-rails, which loads automatically before the app initializes.

PHP

composer require vlucas/phpdotenv


$dotenv = Dotenv\Dotenv::createImmutable( __DIR__ );
$dotenv->load();

$dbUrl = $_ENV['DATABASE_URL'];

// Require specific variables (throws exception if missing)
$dotenv->required(['DATABASE_URL', 'API_KEY']);

Laravel loads .env automatically. Access values with the env() helper:

$debug = env('APP_DEBUG', false);

If you're shipping a Laravel app to production, our zero-downtime Laravel deployment guide walks through build pipelines and environment configuration end to end.

Security Best Practices

The .env file often contains the most sensitive data in your project. Mishandling it is one of the most common security mistakes in web development.

Never Commit .env to Version Control

Add .env to your .gitignore immediately:

.env
.env.local
.env.*.local

If you've already committed a .env file, removing it from .gitignore isn't enough — the values are still in your Git history. Rotate every exposed secret, then use BFG Repo-Cleaner to scrub the history. Our guide to protecting your API keys covers rotation and leak response in more depth.

Use .env.example as a Template

Create a .env.example that documents every required variable with placeholder values:

# .env.example - Copy to .env and fill in real values
DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your-api-key-here
DEBUG=false
PORT=3000

Commit this file. New developers copy it, fill in their values, and they're ready to go.

Restrict File Permissions

On Unix systems:

chmod 600 .env

This ensures only the file owner can read or write it.

Environment-Specific Files

Most frameworks support a hierarchy of .env files that override each other:

.env # Shared defaults (committed)
.env.local # Local overrides (not committed)
.env.development # Development-specific
.env.test # Test-specific
.env.production # Production-specific

The typical loading order (varies by framework):

.env — base defaults
.env.local — local overrides (skipped in test)
.env.{environment} — environment-specific values
.env.{environment}.local — local environment overrides

Vite only exposes variables prefixed with VITE_ to client-side code. Next.js uses NEXT_PUBLIC_. Create React App uses REACT_APP_. These prefixes prevent accidental exposure of server-side secrets to the browser.

Common Patterns and Gotchas

Variable Expansion

Some parsers support referencing other variables:

BASE_URL=https://api.example.com
USERS_API=${BASE_URL}/users
POSTS_API=${BASE_URL}/posts

The dotenv-expand package enables this in Node.js. Python's python-dotenv supports it natively. Not all parsers handle expansion, so test before relying on it.

Multiline Values

Multiline values require double quotes:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF...
-----END RSA PRIVATE KEY-----"

If your parser struggles with this, base64-encode the value instead:

PRIVATE_KEY_BASE64=TUlJRXBBSUJBQUtDQVFF...


const key = Buffer.from(process.env.PRIVATE_KEY_BASE64, 'base64').toString();

Boolean Values

There's no standard for booleans. These are all common:

DEBUG=true
DEBUG=1
DEBUG=yes

Pick one convention and be consistent. Always parse explicitly:

const debug = process.env.DEBUG === 'true';

Configuring Secrets in DeployHQ: UI, CLI, and API

During local development, .env files are convenient. In production, you should not deploy .env files to your servers. Once your secrets are out of your repository, you still need a way to store them and inject them at deploy time. DeployHQ gives you three ways to do that — the web UI, the dhq command-line tool, and the API — so you can pick whichever fits a one-off change or an automated workflow.

Config Files vs Environment Variables

Before configuring anything, it helps to know which of the two mechanisms you actually need:

Config files are whole files uploaded at deploy time and not stored in your repository — think a production .env, a credentials.json, or a settings.yml.
Environment variables are individual values injected into the build and referenced from config files or SSH commands.

The rule of thumb is simple: if you're managing a single value, use an environment variable; if you're managing an entire file, use a config file.

The UI Method

For a one-off change, the DeployHQ web UI is the fastest path.

Config files live under Settings → Config Files. They're uploaded during deployment rather than stored in your repository, which makes them ideal for sensitive data like database configuration. When you create one, you specify:

The full path as the filename (this is where the file lands on the server)
The file content
An optional description
A language for syntax highlighting

Two toggles shape how the file is used. Build Pipeline Integration makes the config file available during your build commands. Server Distribution lets you upload it to all current and future servers and server groups, or target specific ones. You can also set up multiple config files per environment type — development, staging, and production — and only deploy them where they belong. Config files can go out with a standard deployment, or via a dedicated Config file deployment that ships only config files with no other changes.

Environment variables live in the project sidebar under Environment Variables. These are dynamic values usable in config files, SSH commands, and notifications. To create one:

The name must start with a letter and contain only uppercase letters, numbers, and underscores
Enter a value
Toggle Use this variable with the Build Pipeline if the build needs it
Choose which server or server group can access it

In the build pipeline, these are exported as real environment variables, so tools like Vite, Webpack, Next.js, and Create React App read them via process.env.VARIABLE_NAME with no .env file setup at all. In deployments, config files, and SSH commands, you reference them with the %VARIABLE_NAME% syntax.

On security: all variable values are encrypted at rest and never visible in logs or the UI. Values can also be locked , which prevents viewing or changing them while they keep working in deployments. When the same variable is defined at multiple levels, targeting precedence runs highest to lowest: server-specific overrides a server group, which overrides all-servers. DeployHQ also ships roughly 20 built-in variables — such as %environment%, %branch%, %deployer%, and %status% — that you can reference without defining anything.

If you're new to how the build stage fits into a deployment, the DeployHQ build pipeline explains where these variables and files are injected.

The CLI Method

The dhq command-line tool is a single binary that brings the DeployHQ workflow to your terminal — deploy, monitor, manage servers, and automate, all without leaving the shell.

Install it with Homebrew, the install script, or a prebuilt binary:

brew install deployhq/tap/dhq
# or
curl -fsSL https://raw.githubusercontent.com/deployhq/deployhq-cli/main/install.sh | sh

You can also grab a binary directly from GitHub Releases.

Authenticate once with dhq auth login, which stores your credentials in the OS keyring. dhq hello gives you a guided login/signup flow plus project selection, and for CI/CD you authenticate via environment variables instead of the interactive login.

The commands relevant to secrets are:

dhq env-vars — manage a project's environment variables
dhq global-env-vars — manage account-wide environment variables
dhq config-files — manage configuration files
dhq api — reach the full set of 144+ API endpoints

The CLI also offers JSON output for scripting and shell completions for faster typing.

The exact create, set, and update sub-command syntax isn't fixed here — run dhq <command> --help (for example, dhq env-vars --help) to see the current usage for your version rather than guessing at flags.

The API Method

For fully programmatic management, DeployHQ exposes 144+ API endpoints , reachable either through dhq api or directly. This is the right layer when you want to script secret provisioning — for instance, auto-creating a standard set of environment variables and config files every time you onboard a new project or client.

Which One Should You Use?

The CLI and API make your secrets reproducible and automatable, which is exactly what you want when they need to live in CI or in an onboarding script that spins up a new project the same way every time. The UI, by contrast, is the quickest route for a one-off change. Most teams end up using all three: the UI to eyeball and tweak, the CLI and API to codify.

flowchart LR
  A[Code in Git] --> B[DeployHQ]
  B --> C[Build with env vars]
  C --> D[Deploy to server]
  E[Secure variable store] --> B

The end-to-end workflow looks like this:

Development : Use .env files locally
CI/Build : Environment variables and config files set in DeployHQ's project configuration
Deployment : Variables available during build commands and injected into config files
Runtime : Application reads from the server's environment

If you deploy from GitHub or GitLab, DeployHQ connects to your repository and handles the rest. For agencies managing multiple client projects, each project gets an isolated variable store so credentials never leak between clients. This same config-in-the-environment discipline is the backbone of the 12-Factor App methodology, and it applies just as much to a static site on Cloudflare's edge as it does to a traditional server.

Ready to get your secrets out of Git for good? Start a DeployHQ project and add your first encrypted environment variable in a couple of minutes.

FAQ

Should I commit .env.example to Git? Yes. It documents which variables your app requires with placeholder values. Never put real credentials in it.

What happens if a variable is defined in both .env and the system environment? In most libraries, system environment variables take precedence. This lets your deployment platform override defaults without modifying files.

Can I use .env files in Docker containers? Yes. Docker supports --env-file natively, and Docker Compose reads .env in the project root automatically for variable substitution.

How do I handle .env files across a team? Use .env.example as the shared template. Each developer maintains their own .env with local values. For shared secrets, use a password vault rather than distributing files via chat.

Are .env files secure enough for production? For local development, yes. For production, use your platform's built-in secrets management — like DeployHQ's secure environment variables, which are encrypted at rest and injected at deploy time.

Ready to stop worrying about environment configuration? Automate deployments with DeployHQ's build pipeline and manage your environment variables securely from day one. See pricing for team plans.

Questions? Reach out at support@deployhq.com or @deployhq.

Project Folders Are Here: Group Deployments by Client, Team, or Environment

DeployHQ — Tue, 07 Jul 2026 07:59:05 +0000

If your DeployHQ projects list has grown into an endless scroll, you already know the friction: hunting for the right staging project among two dozen others, second-guessing which acme-prod belongs to which client, and losing a few seconds every single deploy. We built project folders to fix exactly that — a simple, new way to group related projects into collections so your dashboard maps to how you actually work.

Folders are especially handy if you run deployments for more than one client, team, or product line. Put everything for a client in a single folder, and their staging site, production site, and supporting microservices sit together instead of scattered across an alphabetical wall of projects.

What project folders actually do

A folder is a collection of projects. Each project belongs to a single folder — it's a flat, one-folder-per-project structure, so there's no nesting to reason about and no ambiguity about where a project lives. You group, you filter, you find what you need. That's the whole idea.

On the Projects page, a sidebar gives you the controls:

All Projects — the full view. Any projects you've marked as favourites float to the top here, regardless of which folder they're in.
Favourites — a quick lane for the projects you touch most.
Your folders — listed alphabetically, each one filtering the view to just its projects when selected.
Ungrouped — everything you haven't filed into a folder yet.

Selecting any sidebar entry filters the main view to match. And crucially, search still spans every project across every folder — so organising into folders never hides anything from you. You get structure when you're browsing and a flat search when you're hunting.

Why this matters for agencies and freelancers

If you manage client work, a crowded projects dashboard is a daily tax. This is where folders earn their keep, and it's the reason we think agencies running deployments across many clients will feel the difference fastest.

The pattern we'd recommend starting with:

One folder per client. Client A's staging environment, production environment, and any microservices all live in the same folder. When Client A calls, you click their folder and everything relevant is right there — no scanning, no guessing. This builds directly on the workflow we covered in how DeployHQ helps web agencies manage multiple projects, giving that multi-client setup a visual home.

Freelancers benefit from the same move at a smaller scale. If you've already ditched SSH and FTP for automated deployments, folders are the next tidy-up: one folder per client keeps a growing roster of side projects and retainers from turning into clutter.

You don't have to organise by client, either. Folders work just as well grouped by:

Team — front-end, platform, data, each with their own collection.
Environment group — separating a batch of internal tooling from client-facing production work.
Product line — one folder per product when you're running several under one roof.

Setting up folders in a couple of clicks

Everything here lives on the Projects page and its sidebar. The full step-by-step lives in the support guide on organising projects into folders, but here's the shape of it.

Create a folder. Any user who can create projects can create a folder, straight from the sidebar. An empty folder doesn't touch your existing projects — nothing moves until you decide it should — so there's no risk in setting up your structure first and filing projects in afterward.

Assign a project to a folder. Two ways:

Open the project, go to its Settings page, pick a folder from the Folder dropdown (or choose No folder to pull it back out), and Save.
Or just drag the project onto a folder in the sidebar to move it.

That drag-and-drop is the fast path when you're doing an initial cleanup and want to file a dozen projects in one sitting.

Ungrouped as an intake lane

Here's a small workflow trick worth adopting: treat Ungrouped as a triage lane rather than a junk drawer. Every new project starts life ungrouped, so that section naturally becomes your needs filing queue. Onboard a new client, spin up their first project, and it waits in Ungrouped until you drop it into the right folder. Glance at Ungrouped periodically and it doubles as a reminder of anything you've set up but not yet organised.

Pair that with Favourites for whatever you're actively shipping this week, and you've got a two-speed system: Favourites for the hot work, folders for the durable structure, and Ungrouped as the inbox in between.

Want to keep your dashboard clean and your pipeline fast? Start deploying with DeployHQ for free and set your folders up on day one.

Permissions: let a lead own the structure

Folder management respects your existing access model, which matters the moment more than one person shares an account. Account administrators and users granted access to all projects can rename and delete folders. Users with limited project access can't — they work within the structure but can't reshape it.

For an agency, that maps cleanly onto real roles. A lead administrator owns the folder structure — deciding that every client gets a folder and keeping the naming consistent — while contractors and junior team members operate inside their scoped access without accidentally renaming or removing a client's folder. If you're formalising who-can-do-what across your pipeline, it's the same access-control thinking auditors expect when they review deployment workflows for SOC 2 compliance.

One reassuring detail: deleting a folder never deletes the projects inside it. Those projects simply become ungrouped, ready to be reassigned. Restructuring is always safe — the worst case is a few projects landing back in the Ungrouped lane.

Take it further: team management for scoped access

Folders organise what you see. To control who can see and touch what, pair them with team management — together they're the complete control story for a shared agency account. Team management is available on DeployHQ's Business and Enterprise plans.

A team is a group of users who share the same permissions and project access. Add someone to a team and they inherit everything that team is granted, so you configure access once rather than fiddling with it per person. Each team sets two things:

Account-level permissions — whether members can create projects, manage users, manage billing, manage the deployment agents, or act as full account administrators.
Project access — either all projects (with the option to exclude sensitive ones) or a hand-picked set of specific projects , with granular control over who can deploy to which servers, update project configuration, and manage config files.

That maps directly onto a folder-per-client layout. Give a contractor team access to only the specific projects for the client they're working on, while your lead administrators keep all-projects access and own the folder structure. Because a user can belong to several teams and their effective access is the combination — the most permissive rule wins — you can layer a can deploy production team on top of a client X team and get exactly the access you'd expect. Teams are created and managed under Settings → Team Management ; the team management guide covers every permission in detail.

Automating folders through the API

Folders are available through the DeployHQ API too, using folder identifiers. The API supports listing, creating, renaming, and deleting folders, along with assigning projects to them.

That opens up the best part for teams that onboard clients regularly: auto-provisioning. Wire folder creation into your onboarding flow and a new client's folder can be created automatically the moment their account is set up, with their first project assigned to it — no manual filing at all. If you've already explored automating your deployment workflows with the DeployHQ API, folder operations slot straight into the same scripts and webhooks you're already running.

A small feature that scales with you

Project folders won't change how a single deploy runs — your build pipelines and zero-downtime releases work exactly as before. What they change is everything around the deploy: how quickly you find the right project, how sensibly a shared account stays organised, and how little friction there is when your project count keeps climbing. If you're still weighing platforms and how they handle scale, our rundown of the best CI/CD tools compared on pricing and features is a good next read.

Set up a folder per client, mark your active work as favourites, and let Ungrouped keep you honest about what still needs filing. It's a few minutes of setup that pays off on every deploy after.

Ready to organise your deployments the way you actually work? Compare DeployHQ plans and get started — folders are part of the projects experience, waiting in the sidebar.

Questions or feedback on project folders? Email us at support@deployhq.com or reach out on X at @deployhq — we'd love to hear how you're organising your projects.

Self-Host Vaultwarden (Bitwarden) on a VPS with Docker

DeployHQ — Tue, 07 Jul 2026 07:18:28 +0000

Vaultwarden is an open-source, Rust-rewritten implementation of the Bitwarden server. It speaks the official Bitwarden protocol, so every Bitwarden client (web, desktop, mobile, browser extensions, CLI) works against it unchanged — but you run it on your own server, store your own data, and stop paying $10 a month for premium features that the official Bitwarden Free tier holds back.

This guide takes you from a fresh VPS to a hardened Vaultwarden instance running at vault.yourdomain.com, with TLS, an admin panel, push notifications for mobile clients, and a backup strategy that doesn't lose your entire vault on a bad disk. It is opinionated about the production setup the official quickstart leaves out.

Why self-host Vaultwarden

The trade-off vs Bitwarden's hosted service is straightforward:

Cost. Bitwarden Free is genuinely useful but capped (no TOTP, no organization sharing, no premium reports). Bitwarden Premium is $10/year per individual or $40/year for families. Vaultwarden gives you all of those features — TOTP, attachments, emergency access, organizations, premium reports — for the cost of a $5 VPS.
Sovereignty. Your encrypted vault never leaves a server you control. Bitwarden's hosted service is highly trusted (zero-knowledge architecture, audited), but if no third party ever touches the encrypted blob is your bar, self-hosting is the only answer.
Performance and latency. A small VPS in your region serves the API faster than Bitwarden's transatlantic infrastructure. Mobile autofill feels snappier.
Single source for your team. Agencies and small companies often want a private vault without paying per-seat. Vaultwarden organizations cover that.

The trade-offs are also honest:

You operate it. Bitwarden handles backups, uptime, security patches, and key rotation. With Vaultwarden, that is on you.
No iOS app review parity. The mobile clients connect to your server fine, but you do not get Bitwarden's enterprise compliance attestations.
Backups are non-negotiable. Lose the SQLite or Postgres data file without backups and every password is gone. There is no recovery.

If you can commit to backups and a 30-minute monthly upgrade window, Vaultwarden is one of the highest-leverage self-hosted services you can run.

Why Docker

Vaultwarden ships an official Docker image (vaultwarden/server:latest) that the project itself recommends as the supported install path. The native binary install is documented but second-class — every release ships a Docker image first. The image is small (~50 MB), the data lives in a single mounted volume, and upgrades are a docker compose pull && docker compose up -d away.

If you have followed our self-host Paperclip with Docker, n8n on Alibaba Cloud Linux 3, or self-host Nextcloud on a VPS guides, the playbook here is identical — only the image and env vars change.

Prerequisites

A VPS with at least 1 vCPU and 1 GB RAM (Vaultwarden is genuinely lightweight). 25 GB SSD covers years of vault growth.
A domain or subdomain (vault.yourdomain.com) with DNS pointing to the VPS.
Docker Engine and the Compose plugin on the VPS — see the easiest way to deploy on a VPS for the broader setup pattern.
An SMTP service (Postmark, SendGrid, Amazon SES, or your provider) for invitations, password hints, and 2FA fallback emails. Free tiers are fine.
A reverse proxy on the VPS — we use Caddy in this guide. Concepts are covered in our reverse proxy 101.

Install Docker on a fresh Ubuntu VPS:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Log out and back in for the group change to apply.

The Compose stack

Vaultwarden's official quickstart shows a one-line docker run. For production, the Compose file below adds Postgres (the SQLite default works but is not what you want for a multi-user setup), proper volume management, healthchecks, and an internal-only port binding so Caddy is the only thing on the public internet.

Create /opt/vaultwarden/docker-compose.yml:

services:
  vaultwarden:
    image: vaultwarden/server:1.32-alpine
    container_name: vaultwarden
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    environment:
      DOMAIN: "https://vault.${DOMAIN_BASE}"
      DATABASE_URL: "postgresql://vault:${DB_PASSWORD}@db:5432/vaultwarden"
      ADMIN_TOKEN: "${ADMIN_TOKEN}"
      SIGNUPS_ALLOWED: "false"
      INVITATIONS_ALLOWED: "true"
      WEBSOCKET_ENABLED: "true"
      SENDS_ALLOWED: "true"
      EMERGENCY_ACCESS_ALLOWED: "true"
      SMTP_HOST: "${SMTP_HOST}"
      SMTP_FROM: "${SMTP_FROM}"
      SMTP_PORT: "587"
      SMTP_SECURITY: "starttls"
      SMTP_USERNAME: "${SMTP_USERNAME}"
      SMTP_PASSWORD: "${SMTP_PASSWORD}"
      LOG_LEVEL: "warn"
      EXTENDED_LOGGING: "true"
    volumes:
      - vw-data:/data
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    container_name: vaultwarden-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: vault
      POSTGRES_DB: vaultwarden
      POSTGRES_PASSWORD: "${DB_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vault"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  vw-data:
  pgdata:

Three details worth flagging.

First, port 80 binds to 127.0.0.1, not 0.0.0.0. Without that prefix, Docker exposes Vaultwarden directly on the public internet, bypassing your ufw/firewalld rules. Caddy on the same host proxies inbound HTTPS to it.

Second, the image is pinned to a version tag (1.32-alpine), not :latest. With a password manager, the version that happened to be in the registry when Watchtower last ran is the wrong upgrade strategy. Pin and upgrade deliberately.

Third, SIGNUPS_ALLOWED: "false" is critical for any vault that lives on the public internet. Without it, anyone who finds the URL can register and start using your server's storage. Use INVITATIONS_ALLOWED: "true" and invite users via the admin panel.

Generate a strong ADMIN_TOKEN — this protects the admin panel at /admin:

openssl rand -hex 64

Vaultwarden recommends an Argon2-hashed token in 1.30+. Generate one with:

docker run --rm -it vaultwarden/server:1.32-alpine /vaultwarden hash

Paste the resulting $argon2id$... string into ADMIN_TOKEN (escape any $ if you put it in a shell-evaluated .env).

Save the secrets to /opt/vaultwarden/.env:

DOMAIN_BASE=yourdomain.com
DB_PASSWORD=$(openssl rand -hex 32)
ADMIN_TOKEN=<the argon2 hash from above>
SMTP_HOST=smtp.postmarkapp.com
SMTP_FROM=vault@yourdomain.com
SMTP_USERNAME=<your postmark token>
SMTP_PASSWORD=<your postmark token>

chmod 600 /opt/vaultwarden/.env. This file is the keys to the kingdom.

TLS via Caddy

Vaultwarden absolutely requires HTTPS. The Bitwarden clients refuse to connect over plain HTTP, and any password manager served over an unencrypted channel is malpractice anyway.

Install Caddy (see our Caddy/Nginx/Apache comparison for why we usually pick Caddy) and write /etc/caddy/Caddyfile:

vault.yourdomain.com {
    reverse_proxy 127.0.0.1:8080

    # WebSocket endpoint for live notifications
    @websockets {
        path /notifications/hub
    }
    reverse_proxy @websockets 127.0.0.1:8080

    encode gzip
    log {
        output file /var/log/caddy/vaultwarden.log
        format json
    }

    header {
        Strict-Transport-Security "max-age=63072000"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "DENY"
        Referrer-Policy "no-referrer"
    }
}

sudo systemctl reload caddy. Caddy fetches a Let's Encrypt cert on first request and renews automatically.

Start the stack:

cd /opt/vaultwarden
docker compose up -d
docker compose logs -f vaultwarden

Visit https://vault.yourdomain.com. You should see the Bitwarden login screen.

First-run: create your account, lock the door

Because we set SIGNUPS_ALLOWED: "false", you cannot register via the public form. Two options:

Option A — temporarily allow signups. Set SIGNUPS_ALLOWED: "true", restart, register your account, then flip it back to false and restart again. Crude but quick.

Option B — invite yourself via the admin panel. Visit https://vault.yourdomain.com/admin, paste your ADMIN_TOKEN, click Users → Invite, enter your email. Click the link in the email and finish account setup.

Option B is the operationally clean version — admin invitations leave an audit trail, and you never have public signups enabled even briefly.

Once you're in, install the Bitwarden clients on your devices and configure the server URL (in the app, before logging in: Self-hosted environment → Server URL: https://vault.yourdomain.com). Your existing Bitwarden vault export imports cleanly via Tools → Import data.

Push notifications for mobile clients

Without push, your iOS and Android Bitwarden apps get vault changes by polling — which means stale data and slow autofill. To get real push:

Register for a free Bitwarden push subscription at bitwarden.com/host/ (the same form Bitwarden uses for self-hosted Bitwarden Server).
They email you installation_id and installation_key.
Add to .env:PUSH_ENABLED=true PUSH_INSTALLATION_ID=<your id> PUSH_INSTALLATION_KEY=<your key> PUSH_RELAY_URI=https://push.bitwarden.com
Restart Vaultwarden. Mobile clients now receive push notifications via Bitwarden's relay (your encrypted blobs never go through it; only the vault changed trigger does).

Backups: the part nobody covers

A Vaultwarden instance without backups is a time bomb. The single Postgres volume (pgdata) plus the vw-data volume (which holds attachments, the RSA keys, and the Sends store) ARE your vault. Lose them, lose everything.

Minimum viable backup:

#!/bin/bash
# /usr/local/bin/vaultwarden-backup.sh
set -euo pipefail

BACKUP_DIR=/var/backups/vaultwarden
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

# Postgres dump
docker exec vaultwarden-db pg_dump -U vault vaultwarden | \
  gzip > "$BACKUP_DIR/db-$TIMESTAMP.sql.gz"

# Data volume (RSA keys, attachments, sends)
docker run --rm -v vaultwarden_vw-data:/data -v "$BACKUP_DIR:/backup" \
  alpine tar czf "/backup/vw-data-$TIMESTAMP.tar.gz" -C /data .

# Retain last 30 days
find "$BACKUP_DIR" -type f -mtime +30 -delete

Schedule it via cron at 0 3 * * *. Then ship the backups off-host — to S3, B2, or another VPS — using restic or rclone. A backup that lives only on the server it backs up is not a backup; it is a hostage situation waiting for a disk failure.

Test restoration once a quarter. The first time you discover your backup script silently failed for six months should not be the day your VPS dies.

Operational concerns

A few things worth setting up before you forget about the box:

Fail2ban for the admin panel and the login endpoint. Vaultwarden ships logs with explicit [ERROR][...login attempt failed] markers; the Vaultwarden wiki has a ready-made jail config. Without this, the /admin endpoint is a brute-force target.
Rotate ADMIN_TOKEN quarterly. Roll a new Argon2 hash, update .env, restart. Cheap, and it limits blast radius if the token leaks.
Disable WEBSOCKET_ENABLED only if you have to. It powers real-time vault updates across logged-in clients; turning it off is a noticeable downgrade.
Monitor disk on the data volume. Attachments and the Sends feature can grow over time. Set a df alert at 80% to avoid waking up to a full disk.
Patch on a schedule. Subscribe to the Vaultwarden releases feed. Pin to a specific patch tag (1.32.7-alpine), test upgrades on a staging VPS first, then promote.

Continuous deployment with DeployHQ

If you maintain a fork of the Vaultwarden repo (custom branding, patched defaults, additional adapters) or simply want every upgrade to be a git push instead of an SSH session, the same continuous-deployment pattern from our Paperclip walkthrough above applies:

Fork dani-garcia/vaultwarden (or just keep your docker-compose.yml and Caddyfile in a private deploy repo — for most users this is enough).
Connect the repo to DeployHQ and configure a Docker build environment — or skip the build and have DeployHQ deploy only the compose file via SSH.
Add the VPS as an SSH server.
Deploy command: docker compose -f /opt/vaultwarden/docker-compose.yml --env-file /opt/vaultwarden/.env pull && docker compose -f /opt/vaultwarden/docker-compose.yml --env-file /opt/vaultwarden/.env up -d.
Push to your production branch when you want to upgrade. Vaultwarden 1.32.6 → 1.32.7 is now a git push away, with the upgrade visible in DeployHQ's audit log.

Wrapping up

You now have Vaultwarden on a VPS with TLS, admin panel access, push notifications, and a backup strategy that survives a disk failure. For under $10/month in VPS plus SMTP costs, you have an unlimited-user Bitwarden-compatible password manager that nobody else can read or revoke.

If you're running this for a small team or family, start a free DeployHQ trial so the next Vaultwarden upgrade is a git push instead of an SSH session. Pricing is on the plans page; the agency plan covers running Vaultwarden plus a dozen other self-hosted apps across multiple client VPSes.

Questions about Vaultwarden, backup strategy, or wiring up automated upgrades? Email us at support@deployhq.com or ping @deployhq on X.

How to Let AI Query Your Database Without Deleting It: Read-Only Guardrails for Claude Code

DeployHQ — Mon, 06 Jul 2026 09:04:36 +0000

A story made the rounds recently that put a chill down the spine of every developer experimenting with AI coding tools: someone gave an AI assistant live access to a production database, asked it to help clean things up, and watched it issue destructive commands that wiped real data. The specifics vary depending on who's telling it, but the shape of the story is always the same — an autonomous agent, a real connection string, write permissions, and no seatbelt.

Here's the uncomfortable truth: the AI wasn't malfunctioning. It did exactly what it was designed to do — generate and execute a plausible-looking command to accomplish the goal it was given. The failure wasn't the model. The failure was the access. We handed a probabilistic text generator the same keys we'd hesitate to give a brand-new junior engineer on their first day, and then acted surprised when it used them.

The good news is that this is an entirely solvable problem, and the solution isn't never let AI touch your database. AI is genuinely useful for exploring schemas, drafting queries, and debugging slow reports. The fix is to make destructive actions impossible, not just discouraged. This guide walks through the concrete guardrails — real GRANT statements, MCP-layer flags, sandbox patterns, and connection scoping — that let an AI query your database all day long without ever being able to delete it.

Why write access to prod goes wrong

Before the recipe, it's worth being precise about the failure mode, because the AI went rogue is the wrong mental model and leads to the wrong fixes.

When you connect an AI coding assistant to a database — usually through a Model Context Protocol server that bridges the model and your data — the model doesn't understand your data the way you do. It pattern-matches. Ask it to remove the test accounts and, if the connection it's been handed can run DELETE and DROP, it may generate a statement that's syntactically valid, semantically reasonable-looking, and catastrophically wrong: a missing WHERE clause, a TRUNCATE on the wrong table, a schema-altering migration it invented on the spot.

Three factors compound the risk:

Autonomy. Agentic tools chain actions together. A single prompt can trigger a sequence of tool calls with no human confirming each SQL statement before it runs.
Confidence without comprehension. The model has no model of this data is irreplaceable. It weighs a DROP TABLE the same way it weighs a SELECT.
Overprivileged connections. Most developers connect using their personal credentials or the app's connection string — both of which typically carry full read/write/DDL rights.

Fix the third factor and the first two stop mattering. If the connection physically cannot execute a DELETE, it does not matter how confidently the AI generates one. That's the principle everything below is built on.

The read-only principle: dedicated roles, not shared credentials

The single highest-leverage guardrail is also the oldest one in the database security playbook: give the AI its own database role, and grant that role only SELECT. No INSERT, no UPDATE, no DELETE, no DROP, no DDL. If the tool's only job is to read and analyze, it never needs anything else.

This is defense the database itself enforces. It doesn't rely on the AI behaving well, on a system prompt being obeyed, or on a middleware layer catching a bad command. The permission simply isn't there.

Here's the recipe for each of the big three.

PostgreSQL — create a login role, grant connect and read, and (critically) set default privileges so future tables are covered too:

-- 1. Create a dedicated, least-privilege login role
CREATE ROLE ai_readonly WITH LOGIN PASSWORD 'use-a-strong-secret-from-your-vault';

-- 2. Allow it to connect and read the schema
GRANT CONNECT ON DATABASE myapp TO ai_readonly;
GRANT USAGE ON SCHEMA public TO ai_readonly;

-- 3. Grant SELECT on all *existing* tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_readonly;

-- 4. Make sure tables created *later* are also readable (this is the step people forget)
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO ai_readonly;

The ALTER DEFAULT PRIVILEGES line matters: without it, the AI role silently loses visibility every time you add a table, and someone fixes it later by granting something broader. Lock it down once, correctly.

MySQL / MariaDB — the same idea, scoped to SELECT only:

CREATE USER 'ai_readonly'@'%' IDENTIFIED BY 'use-a-strong-secret-from-your-vault';
GRANT SELECT ON myapp.* TO 'ai_readonly'@'%';
FLUSH PRIVILEGES;

Because GRANT SELECT ON myapp.* is scoped at the database level, it automatically applies to tables you create later — no default-privileges dance required. Tighten the host portion ('ai_readonly'@'10.0.%') to your network rather than '%' wherever you can.

SQL Server — this one is almost too easy, because it ships with a built-in role for exactly this purpose:

CREATE LOGIN ai_readonly WITH PASSWORD = 'use-a-strong-secret-from-your-vault';
CREATE USER ai_readonly FOR LOGIN ai_readonly;

-- db_datareader = SELECT on every current and future table in the database
ALTER ROLE db_datareader ADD MEMBER ai_readonly;

db_datareader grants SELECT on all user tables and views, current and future, and nothing else. It's the SQL Server answer to read everything, change nothing.

Whatever engine you're on, verify the guardrail the fun way: connect as the new role and try to break something. Run a DELETE or a DROP. You want a permission-denied error. If you get one, the AI will too — and no prompt injection, no hallucinated migration, no missing WHERE clause can get past it.

Setting up a least-privilege role is a one-time job that pays off every time an AI — or a script, or a new hire — touches your data. If you're already thinking about who can change what and when, that same discipline belongs in your deployment process: DeployHQ's build pipelines let you gate exactly which commands run against an environment, so schema changes go through review instead of an ad-hoc terminal session. More on that below.

Guardrails at the MCP layer

The read-only role is your backstop. The MCP server is your second line of defense, and it's worth configuring even when the role is already locked down — belt and suspenders.

Most AI database access flows through an MCP server that translates the model's requests into real queries. If you're new to the pattern, our complete guide to building an MCP server covers how these bridges work, and our roundup of the best MCP servers for web developers covers the ecosystem. For databases specifically, DBHub is a common choice, and it exposes two flags that matter here:

--readonly — DBHub refuses to execute any query that isn't a read. Even if the AI generates a DELETE, the server rejects it before it reaches the database. This is a software-layer mirror of your read-only role, and having both means a misconfiguration in one doesn't expose you.
--max-rows — caps the number of rows any single query can return. This defends against a different failure: not destruction, but a runaway SELECT * FROM events on a billion-row table that pins your database's CPU and memory. Set a sane ceiling (a few thousand rows) so an over-eager query degrades gracefully instead of taking prod down.

A typical hardened DBHub invocation looks like this:

dbhub --transport stdio \
  --dsn "postgres://ai_readonly:...@db-host:5432/myapp?sslmode=require" \
  --readonly \
  --max-rows 5000

Note the DSN uses the ai_readonly role from the previous section, not your admin credentials. The flags and the role reinforce each other. (DBHub's flags are documented in the DBHub repository — worth reading before you wire it up.)

If you're running this inside Claude Code, the Claude Code cheatsheet is a handy reference for the CLI flags and permission settings you'll touch while setting this up.

The sandbox pattern: give it a copy it can't hurt

Read-only access covers the vast majority of what you'd actually want an AI to do with a database — explore, analyze, draft queries. But sometimes you genuinely need it to write: test a migration, populate seed data, validate that a DELETE does what you expect. For anything destructive, the rule is simple: never do it against a database you care about.

The pattern is a disposable copy:

Snapshot or restore a copy of the relevant data into a throwaway database — a local container, an ephemeral schema, or a restored backup on a scratch instance.
Point the AI at the copy. Give it a full read/write role on that copy only. Now it can DELETE, TRUNCATE, and ALTER to its heart's content.
Throw it away when you're done. Nothing the AI did touched production.

A Docker-based scratch database is the fastest version of this:

# Spin up a disposable Postgres the AI can freely mutate
docker run --rm -d --name ai-sandbox \
  -e POSTGRES_PASSWORD=sandbox \
  -p 5433:5432 postgres:16

# Load a sanitized dump into it
pg_restore -h localhost -p 5433 -U postgres -d postgres ./sanitized-dump.dump

Two things make this safe rather than just convenient. First, the --rm flag means the container — and everything the AI did to it — evaporates when you stop it. Second, and non-negotiable for anything derived from production: sanitize the dump. Strip or mask PII before it lands anywhere an AI (and, via the model provider, potentially a third party) can read it. A sandbox that leaks real customer data isn't a safe sandbox.

A file-based engine makes this pattern even cheaper: with a local SQLite database, a disposable copy is a single cp command — you experiment where undo is free, then promote.

Connection scoping: SSH tunnels, TLS, and env-not-config

Even a perfectly permissioned read-only role is a liability if the credentials leak or the connection is exposed. Scope the connection itself.

Don't expose the database to the internet. The AI tool should reach your database over an SSH tunnel or a private network, not a publicly routable port. An SSH tunnel forwards a local port through an authenticated, encrypted channel:

# Forward local :5432 to the DB, reachable only via the bastion host
ssh -L 5432:db-internal:5432 deploy@bastion.example.com -N

Then point the AI at localhost:5432. The database's real port never faces the public internet. If you're already comfortable running deploy commands over SSH, this will feel familiar — our SSH commands reference covers the connection patterns.

Require TLS. Encrypt the connection so credentials and query results can't be sniffed in transit. In Postgres that's ?sslmode=require (or stricter — verify-full — if you've got the CA set up) on the DSN; MySQL and SQL Server have equivalents.

Keep credentials in the environment, not in config files. This is where a lot of otherwise-careful setups fall down. A connection string with a password committed to a mcp.json, a .env that's accidentally tracked, or a config file synced to a dotfiles repo is a credential leak waiting to happen. Reference secrets from environment variables or a secrets manager, and make sure the config that does get committed contains only variable references:

// good: no secret in the file
{ "dsn": "${DATABASE_URL_READONLY}" }

If you're setting up Claude Code for the first time, our getting-started guide for the terminal AI assistant walks through where its config lives and how to keep secrets out of it.

Guardrails are worth setting up once and reusing everywhere. If you'd rather your infrastructure enforce these boundaries by default — scoped credentials, encrypted connections, reviewed changes — that's exactly the discipline DeployHQ's deployment features are built around. Wire your database changes into a pipeline instead of a prompt.

Where deploys fit: schema changes belong in a pipeline

Here's the part most AI database safety advice skips entirely. Once you've locked the AI down to read-only, a fair question is: how do the actual, intended changes get made? Schema migrations, new indexes, column additions — those still need to happen.

The answer is emphatically not temporarily grant the AI write access and let it run the migration over SSH. That reintroduces every risk you just eliminated, plus a new one: an unreviewed, unlogged, unrepeatable change to production with no rollback path.

Schema changes belong in a reviewed build pipeline , the same way application code does. The migration is written (with the AI's help, drafting against a sandbox is great) and committed to version control. It's reviewed by a human. It runs as a deploy step, in order, with the change logged and the previous state recoverable. This is exactly the model in our guide to database migration strategies for zero-downtime deployments, and the broader practice of making database deployments repeatable and reversible.

The contrast is stark:

Ad-hoc AI SSH session	Reviewed deploy pipeline
Runs immediately, no review	Human reviews before it runs
No record of what changed	Every change logged
No rollback	One-click rollback to the prior state
Runs as an over-privileged user	Runs as a scoped deploy identity
Not repeatable across environments	Same migration, staging then prod

When a schema change is a version-controlled, reviewed deploy step, the fact that an AI helped write it is no longer scary — because the AI never executed it against prod. A human did, through a system built to make that action safe, observable, and reversible. Rolling migrations into a broader zero-downtime deployment strategy means even the intended changes never take the site down.

This is the whole philosophy in one line: let AI draft, let a pipeline deploy.

The copy-paste safety checklist

Print this, pin it, run through it before you connect any AI tool to any database that has data you'd miss.

AI + DATABASE ACCESS — SAFETY CHECKLIST

ROLE
[] AI connects via a DEDICATED database role, not personal or app credentials
[] That role has SELECT only — no INSERT/UPDATE/DELETE/DROP/DDL
[] Postgres: ALTER DEFAULT PRIVILEGES set so future tables stay read-only
[] SQL Server: role added to db_datareader (nothing broader)
[] Verified by connecting as the role and confirming DELETE/DROP is denied

MCP LAYER
[] MCP server (e.g. DBHub) launched with --readonly
[] --max-rows set to a sane ceiling to prevent runaway result sets
[] DSN uses the read-only role, never admin credentials

DESTRUCTIVE WORK
[] Any write/migration testing happens on a DISPOSABLE copy, never prod
[] Copies are PII-sanitized before the AI can read them

CONNECTION
[] Database is NOT exposed on a public port (SSH tunnel or private network)
[] TLS/SSL required on the connection (sslmode=require or stricter)
[] Credentials live in env vars / secrets manager, NOT in committed config

DEPLOYS
[] Schema changes go through a reviewed, version-controlled pipeline
[] No temporary write grants for "just this one migration"
[] Every change is logged and has a rollback path

Work down that list and the viral horror story simply can't happen to you. Not because your AI is smarter or better-behaved than the one in the story — but because you removed its ability to do harm in the first place. That's what security by design looks like: the safe path is the only path available.

This is the first article in our series on working safely with AI and databases, with companion deep-dives on MySQL-specific connection gotchas and a disposable-file SQLite workflow to follow.

Ready to move database changes out of ad-hoc terminal sessions and into a reviewed, reversible pipeline? Start deploying with DeployHQ for free and give your schema changes the same guardrails you just gave your AI.

Questions or want to share how you've locked down AI database access? Email us at support@deployhq.com or find us on X at @deployhq.

DeployHQ Static Hosting vs Cloudflare Pages: Same Edge, Different Workflows

DeployHQ — Fri, 03 Jul 2026 05:38:32 +0000

Choosing between DeployHQ Static Hosting and Cloudflare Pages is unusual in this category — both products serve your static site from the same Cloudflare edge network. The HTML, CSS, JavaScript, and images travel through the same 305+ POPs, get cached the same way, and exit at the same latencies. So the comparison isn't about CDN performance. It's about everything that happens before the file lands on the edge — the build pipeline, what else you can deploy from the same project, and how tightly you want to be coupled to the Cloudflare ecosystem.

This guide compares the two head to head: where the products diverge despite the shared edge, current pricing, and when to pick which.

TL;DR

If you're already deep in the Cloudflare stack — Workers for compute, R2 for object storage, KV for caching, D1 for SQL, Cloudflare DNS — Cloudflare Pages is the obvious answer. The native integration is excellent and the free tier is unusually generous (unlimited bandwidth, unlimited static requests).

If you also deploy backend code somewhere other than Cloudflare (a Laravel API on a VPS, a Rails app on a managed server, a WordPress install on shared hosting), DeployHQ Static Hosting puts the static site on the same Cloudflare edge that Pages uses while the same DeployHQ project ships your backend code to wherever it actually runs. One pipeline, one billing relationship, no Cloudflare lock-in for the parts of your stack that don't belong there.

For broader context across the category, our roundup of the best software deployment tools in 2026 covers Cloudflare Pages, DeployHQ, Vercel, and Netlify alongside the wider toolset. For the direct head-to-heads against the other edge hosts, see DeployHQ Static Hosting vs Vercel and DeployHQ Static Hosting vs Netlify.

At a glance: feature comparison

Capability	DeployHQ Static Hosting	Cloudflare Pages
Edge network	Cloudflare's global edge	Cloudflare's global edge (same network)
Framework auto-detection	Yes (rule + AI fallback)	Yes
Atomic deploys	Yes	Yes
Custom domains + SSL	Yes (automatic)	Yes (automatic)
Free tier bandwidth	Trial site included	Unlimited bandwidth (all tiers)
Build minutes	Bundled with DeployHQ plan	500/month Free, 5,000/month Pro
Concurrent builds	1 (parallelism via separate projects)	1 Free, 5 Pro, 20 Business
SPA mode (client-side routing)	Yes (toggle)	Yes (`_redirects` or `_routes.json`)
Server-side rendering	No (static only)	Limited via Workers (Pages Functions)
Edge functions	No	Yes (Pages Functions, Workers-based)
Native integrations	DeployHQ deployment pipeline	Workers, R2, KV, D1, Queues, AI
Backend deploys in same pipeline	Yes (VPS, shared host, cloud, S3)	Workers / Pages-only
Pricing model	Fixed monthly per site	Free / $20/mo Pro / $200/mo Business
Lock-in level	Low (artifact moves anywhere)	Medium (Pages Functions ↔ Workers tied)

Same edge. Different everything else.

When DeployHQ Static Hosting is the right choice

You already deploy a backend with DeployHQ — or are planning to. This is the strongest case. If you're shipping a static site plus a Laravel/Rails/Node backend, having both in one DeployHQ project means one set of deploy keys, one rollback surface, one billing relationship. The same workflow that ships your Hugo marketing site can ship your Express API to a DeployHQ Managed VPS — or to your own Hetzner box, or to shared hosting, depending on what fits. Cloudflare Pages can only deploy to Cloudflare; everything outside the Cloudflare ecosystem still needs a separate deployment workflow.

You want the same DeployHQ pipeline running your build. DeployHQ's build pipeline is intentionally generic — install dependencies, run tests, compile assets, set environment variables, run pre-deploy hooks. The build step doesn't care whether the destination is Static Hosting, a VPS, or an S3 bucket. If you've already tuned that pipeline for your project, deploying to Static Hosting requires no changes to it. See the SvelteKit deployment guide for a representative pipeline example.

You want predictable per-site pricing. Cloudflare Pages' free tier is the most generous in the category — unlimited bandwidth, unlimited static requests. That's hard to beat for a hobby project. But the Pro tier ($20/mo annual, $25/mo monthly) caps build minutes at 5,000/mo and concurrent builds at 5; Business jumps to $200/mo. DeployHQ Static Hosting charges a fixed monthly rate per site on top of your DeployHQ plan — useful when you're running multiple client sites and want a flat per-site cost regardless of build complexity. Compare current DeployHQ plans for the full breakdown. For broader trade-offs across hosting models, our shared hosting vs VPS guide for junior developers covers the wider category.

You want low lock-in. Pages Functions are written in the Workers runtime — if you migrate away, you rewrite them. DeployHQ Static Hosting serves a generic build artifact; if you ever want to leave, your build still produces the same files and works anywhere else that serves static content.

When Cloudflare Pages is the right choice

You're all-in on the Cloudflare stack. Workers for compute, R2 for object storage, KV for caching, D1 for SQL, Queues for messaging — Cloudflare Pages is the natural front door to that ecosystem. Direct bindings to Workers, R2, and KV from Pages Functions remove a lot of glue code. If your architecture is everything on Cloudflare, Pages is the lowest-friction static-hosting choice you can make.

You need the free tier specifically. Pages' free tier with unlimited bandwidth and unlimited static requests is unique in this category. For high-traffic hobby projects, marketing pages with viral spikes, or open-source documentation sites, that pricing structure can't be matched. DeployHQ Static Hosting doesn't have a directly comparable free forever tier — the trial includes a site and paid plans start from there.

You want Pages Functions for per-request logic. Geo-routing, A/B testing at the edge, authentication, header manipulation, simple APIs — Pages Functions running on Workers handles those cleanly. DeployHQ Static Hosting doesn't run code at request time; you'd put Cloudflare Workers in front of it to get the same behavior (which works, but isn't bundled).

You're not deploying anything outside Cloudflare. If your entire architecture lives in Cloudflare's ecosystem and you don't have backend services on VPS, shared hosting, or cloud platforms that DeployHQ would otherwise handle, the workflow-consolidation argument for DeployHQ doesn't apply. Stay on Pages.

Pricing: side by side

As of June 2026 — check vendor pages for current numbers.

Cloudflare Pages Free is $0 with 1 concurrent build, 500 builds/month, 100 custom domains per project, unlimited bandwidth, unlimited static requests. Genuinely the most generous free tier in the category.

Cloudflare Pages Pro is $20/month annual or $25/month monthly with 5 concurrent builds, 5,000 builds/month, 250 custom domains per project, unlimited bandwidth, unlimited static requests.

Cloudflare Pages Business is $200/month annual or $250/month monthly with 20 concurrent builds, 20,000 builds/month, 500 custom domains per project.

DeployHQ Static Hosting charges a fixed monthly rate per site, shown on the Hosted Resources page in your account's currency. Pricing rolls into your DeployHQ plan on a single monthly invoice. Trial accounts can provision one Static Hosting site at no charge.

The honest framing: for a single static site with no backend, Cloudflare Pages Free is structurally cheaper than any DeployHQ tier because Free is $0. The DeployHQ math gets favorable when you're already paying for DeployHQ to deploy backend code somewhere — at that point the static site is bundled into a plan you're already running, and the marginal cost of adding Static Hosting is the per-site rate, not a new vendor relationship.

Moving between them (it's not all-or-nothing)

Both platforms serve the same static artifact, so migration in either direction is mostly DNS plus repo reconfiguration.

From Cloudflare Pages to DeployHQ Static Hosting: connect the repository in DeployHQ, point Static Hosting at the same build output directory Pages used, keep the build command identical, switch DNS once verified. If you depend on Pages Functions, plan replacements first — Cloudflare Workers in front of Static Hosting can serve the same role, but you maintain them separately rather than co-located with the static project.

From DeployHQ Static Hosting to Cloudflare Pages: even simpler — connect the repo to Pages, set the same build command and output directory, switch DNS. Nothing DeployHQ-specific in your code to unwind.

Or: use both. Run your static frontend on Cloudflare Pages, keep DeployHQ as your deployment pipeline for the backend you ship to a VPS or shared host. This combination is common — Pages handles the frontend exceptionally well, DeployHQ handles everything else. The trade-off is two deployment surfaces instead of one; whether that's worth it depends on how much your team values consolidation.

For broader background on legacy hosting and modern alternatives, is FTP dead? covers the wider shift in deployment patterns.

The shared-edge dimension

Both products use Cloudflare's edge. In practice this means:

Latency : identical from a given user's location. There's no advantage to either product on raw edge performance for static content.
DDoS protection : included on both via Cloudflare's standard protection.
HTTPS certificates : provisioned automatically by Cloudflare in both cases.
Cache invalidation : works at deploy time (atomic deploys flip the served version) in both products.

What's different despite the shared edge:

Cloudflare account requirement : Pages is part of your Cloudflare account; you log in there, your billing lives there, your custom domains route through Cloudflare DNS. Static Hosting doesn't require a Cloudflare account — it manages the Cloudflare infrastructure on your behalf.
Workers bindings : Pages Functions can bind directly to Workers, R2, KV, D1, Queues. Static Hosting doesn't expose these bindings — if you need them, you front the Static Hosting site with your own Worker that has the bindings.
Pre-edge build pipeline : DeployHQ's build runs on DeployHQ's servers with its own pipeline UI, env-var management, and rollback history. Cloudflare Pages runs builds on Cloudflare's infrastructure with its own UI. They produce the same artifact but the pre-edge experience differs.

DeployHQ also exposes one-click rollback — useful when you ship something broken and need to revert without rebuilding. Pages supports a similar flow through its deployment history UI, but the DeployHQ rollback is the same one-click motion you'd use for a Managed VPS deploy or a BYO-server deploy. One mental model across all targets.

FAQ

Are there any latency differences between DeployHQ Static Hosting and Cloudflare Pages?No. Both serve from Cloudflare's global edge network. Latency to a given user depends on their geography and the nearest Cloudflare POP — which is identical for both products.

Does DeployHQ Static Hosting use my own Cloudflare account?No. DeployHQ manages the Cloudflare infrastructure on your behalf. You don't need a Cloudflare account to use Static Hosting; subdomains under deployhq-sites.com work out of the box, and custom domains use a CNAME from your DNS provider.

Can I use Cloudflare Workers in front of DeployHQ Static Hosting?Yes. If you need edge-function behavior (geo-routing, edge auth, request rewriting), set up a Cloudflare Worker on your custom domain that proxies to your Static Hosting subdomain. The Worker runs at the edge with full Worker capabilities.

What about Hugo, Astro, Eleventy, and other static-site generators? Both products support all major static-site generators since they serve the build artifact, not the source. See the Hugo deployment guide for a representative DeployHQ pipeline example.

What if I outgrow Static Hosting and need a runtime? Move the project to DeployHQ Managed VPS Hosting (for full Linux + Node/Python/Ruby), or front Static Hosting with Cloudflare Workers for lightweight edge logic. Same DeployHQ pipeline ships to either target.

Get started

If you're already on DeployHQ, enable beta features under Settings > Beta Features and add a new Static Hosting server to any project. The Static Hosting on DeployHQ pillar guide walks through the end-to-end provisioning flow.

If you're new, start a free trial and the included Static Hosting site lets you compare it head-to-head against Cloudflare Pages for the same project. For the wider picture of where Static Hosting fits among the five hosting types DeployHQ supports, see your universal deployment and hosting platform.

Both DeployHQ Static Hosting and Cloudflare Pages serve from the same edge, and both do the static-hosting job well. The right answer depends almost entirely on what's around your static site. If your stack is all-Cloudflare, Pages wins on integration and free-tier economics. If you also ship backend code outside Cloudflare — and especially if you want one deployment pipeline for the whole stack — DeployHQ Static Hosting wins on workflow consolidation.

For more detail on the product, the Static Hosting support library has the full provisioning, framework-detection, and lifecycle documentation.

Questions or feedback on Static Hosting vs Cloudflare Pages? Email support@deployhq.com or follow @deployhq on X for product updates.

Free Static Hosting for v0, Bolt, Lovable, and Firebase Studio Apps

DeployHQ — Tue, 30 Jun 2026 07:39:28 +0000

You describe an app in a chat window. Twenty seconds later you're staring at a working React UI that does roughly what you asked for. v0, Bolt, Lovable, and Firebase Studio have made the first hour of building a web app look almost magical — and the next hour is when reality lands. Where does this thing actually live? Whose name is on the URL? Who pays the bill?

The defaults each of these tools nudge you toward all share one trait: lock-in. v0 ships you to Vercel. Bolt has a one-click button to Netlify. Lovable hosts at <project>.lovable.app until you upgrade. Firebase Studio assumes Firebase Hosting. Each of those is a fine first step — they're free, they work in two clicks, they give you a URL to share. They also bind you to one ecosystem's pricing, runtime, and account terms the moment you want to move past the demo.

This isn't a hypothetical migration — it's a pattern users are already documenting. The r/lovable thread sorry Lovable, but I moved on is one recent example: OP and the top commenters describe the same workflow shift — keep the AI builder for the initial scaffold, then continue editing in your own editor with Claude Code or Cursor, with Supabase still doing the backend, and free hosting on top. That last bullet is the one this post addresses. Most migrants land at Vercel because it's the most visible free option; this is the alternative.

DeployHQ Static Hosting is the lock-in-free alternative for the static frontend these tools produce. It runs on Cloudflare's global edge, framework-detects your build (Next.js, Vite, Astro, Angular, SvelteKit, Flutter web), and atomically deploys every Git push. It's free during beta. And it doesn't touch the backend you've already wired up — Supabase, Firebase, your own API, whichever the tool of your choice put behind your UI.

The pattern: where each AI builder leaves you

Builder	Default deploy target	What you can move	What you can't
v0	Vercel	The Next.js project (with static export configured)	Server actions, App Router server components, route handlers
Bolt	Netlify	Vite + React/Vue/Svelte, Astro, SvelteKit static, Next.js export	The `server/` directory in full-stack starters
Lovable	`*.lovable.app` (custom domains paid)	The Vite + React frontend	Custom Node servers you've added beyond Supabase Edge Functions
Firebase Studio	Firebase Hosting	Next.js export, Angular, Vite, Astro, Flutter web	Firebase App Hosting (Cloud Run SSR), `firebase.json` rewrites

The pattern: anything that compiles to a flat output directory — dist/, out/, build/ — moves cleanly to Static Hosting. Anything that needs a Node runtime at request time — server actions, SSR, route handlers, your own Express/Hono backend — doesn't, and shouldn't try to.

For the parts that don't fit static, DeployHQ Managed VPS is the upgrade path (covered in detail below). Same DeployHQ project, same build pipeline, different deploy target. You don't have to choose one or the other at the start.

The four how-to guides

Each of the tools has its own export flow, framework defaults, and a handful of gotchas worth knowing before the first push. Walk through whichever guide matches your starting point:

v0 : How to Deploy a v0 App to DeployHQ Static Hosting — covers exporting from v0 to GitHub, switching Next.js into static-export mode, and the server-action gotchas v0 sometimes generates.
Bolt : How to Deploy a Bolt App to DeployHQ Static Hosting — works across every framework Bolt scaffolds. Includes the WebContainer path-cleanup gotcha and the framework→output-directory mapping for Vite, Astro, SvelteKit, Next, and Remix.
Lovable : How to Deploy a Lovable Frontend to DeployHQ Static Hosting — keeps the Supabase backend intact and walks through updating Supabase Auth redirect URLs for the new domain. The static frontend, your Supabase backend keeps doing the work path.
Firebase Studio : How to Deploy a Firebase Studio App to DeployHQ Static Hosting — covers the framework-agnostic build configuration, the Firebase Auth authorized-domains update, and the carve-out around Firebase App Hosting.

All four follow the same shape: export to GitHub, point DeployHQ at the repo, configure the build pipeline with the right framework env-var prefixes, ship the first deploy, then update auth allowlists if the backend you're calling has one.

What stays the same when you move

The biggest reason people stall on moving an AI-built app off its default host is the worry that auth and data will break. They almost never do.

Supabase-backed projects (Lovable's default and a common pattern in v0/Bolt) keep working because Supabase's API and Auth flows are hosted on Supabase. You set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in DeployHQ's environment-variable UI, add the new domain to Supabase's redirect-URL allowlist, and the rest is unchanged.
Firebase-backed projects (Firebase Studio's default, sometimes appears in other builders) keep working because Firebase Auth, Firestore, Storage, and Cloud Functions all run on Google's infrastructure. You add the new domain to Firebase Auth's authorized-domains list and the SDK keeps talking to the same backend it always did.
Apps calling third-party APIs directly (Stripe checkout, public REST APIs, scraped data sources) keep working because those calls leave the browser regardless of where the bundle is served from.

The only things that genuinely move are the build pipeline (now run by DeployHQ instead of Vercel/Netlify/Firebase) and the public URL (now Cloudflare's edge instead of Vercel/Netlify/Firebase Hosting). Everything between user and database stays put.

Why this is worth the 15 minutes

The first deploy from an AI builder's default host is essentially free. The second one — when the demo becomes a real project — is where the trade-offs start mattering:

Lock-in. Each builder's default host is owned by a different company. Moving later is harder than picking your own host up front, because URLs accumulate users, integrations, and SEO equity that don't migrate cleanly.
Pricing trajectory. Vercel's bandwidth and serverless-execution pricing scales with traffic. Netlify's build-minute caps bite earlier than you'd expect on a chatty Vite project — the DeployHQ Static Hosting vs Netlify comparison covers where those thresholds land. *.lovable.app is fine for demos but custom domains are a paid Lovable plan. Firebase Hosting traffic is metered against the same Firebase Spark/Blaze quotas as your database calls.
Runtime constraints you didn't agree to. Vercel's static export still goes through Vercel's edge-function billing model. Netlify's bandwidth tier resets monthly. Firebase Hosting can serve static files but pulls you into the broader Firebase plan structure.

DeployHQ Static Hosting is free during the beta, and the post-beta plan structure is straightforward enough to put on a single DeployHQ pricing page — covered in the same way the rest of the DeployHQ catalog is priced, with no per-invocation runtime metering on a static bundle.

For the head-to-head against the most common alternatives, read the DeployHQ Static Hosting vs Vercel comparison — it covers framework support, pricing, edge network, and the trade-offs that decide which one fits your stack. The Static Hosting pillar guide is the longer reference on framework auto-detection, SPA mode, atomic deploys, and the rest of the feature surface.

What Static Hosting isn't for

Three categories of project don't belong on Static Hosting, and it's worth saying so up front:

Anything with required SSR at request time. Next.js with server actions, Astro with server-side render, SvelteKit with the Node adapter, full Next.js App Router server components — these need a Node runtime Static Hosting doesn't provide. Move them to Managed VPS or refactor to static export.
Full-stack starter templates with bundled servers. Bolt's full-stack starters include an Express or Hono server. Lovable projects that have grown a custom WebSocket layer beyond Supabase Edge Functions. v0 projects you've turned into half-static, half-SSR hybrids. The static frontend half deploys fine; the server half needs to live somewhere with a runtime.
Firebase App Hosting projects. Firebase Studio's newer App Hosting target provisions a Cloud Run instance for SSR — that runtime is fundamentally Google-bound and can't move to Static Hosting.

In all three cases, DeployHQ Managed VPS is the natural home — same DeployHQ project, same Git workflow, different deploy target. You can also split the difference: keep the static UI on the edge and run only the dynamic parts on Managed VPS. The build pipeline you set up adapts to either target.

How to start

If you're already an AI-app-builder user with a project ready to move:

Pick the guide that matches your tool (v0, Bolt, Lovable, Firebase Studio — links above)
Export to GitHub if you haven't already
Sign up free for DeployHQ — the beta-tier Static Hosting site is included
Walk through the guide; the whole loop is under 20 minutes

If you're earlier in the journey and still deciding which builder to use, the framework support is the right way to choose: Static Hosting framework-detects every common output, so the question is really which builder's UX you prefer and which backend (Supabase, Firebase, your own) you want behind it. The hosting decision compounds: pick a lock-in-free host now and you keep the option to swap the builder later.

For the broader DeployHQ catalog beyond static, the hosting hub covers the four other deploy targets DeployHQ supports — Managed VPS, SFTP, SSH/Rsync, S3 — all driven from the same project and build pipeline. And for context on the proposition across the full hosting catalog, your universal deployment and hosting platform is the longer read.

The full product reference lives in the Static Hosting support library. And for a roundup of how DeployHQ fits alongside the rest of the deployment-tool category, best software deployment tools in 2026 is a useful next reference.

Questions, edge cases, or a builder you'd like covered that isn't in the list above? Email support@deployhq.com or follow @deployhq on X — we're adding to this list as more AI builders ship credible static-export paths.

How to Deploy a Firebase Studio App to DeployHQ Static Hosting

DeployHQ — Fri, 26 Jun 2026 14:11:37 +0000

DeployHQ Static Hosting serves pre-built static assets from Cloudflare's global edge — a clean fit for a Firebase Studio project, where Gemini Code Assist scaffolds a Next.js, Angular, or Vite-based frontend that builds to a flat output directory. This guide walks through deploying a Firebase Studio app end to end: sync the workspace to GitHub, configure the framework for static export, provision Static Hosting, set up the build pipeline, update Firebase Auth's authorized domains, and ship the first deploy.

The framing matters: Static Hosting replaces the Firebase Hosting URL Firebase Studio provisions by default, not the Firebase backend behind it. Firebase Auth still issues tokens. Firestore still stores data. Cloud Functions still run on Google's infrastructure. Static Hosting is the public face — a faster, lock-in-free home for the frontend bundle that calls all of it. The one exception: if you've enabled Firebase App Hosting (which provisions a Cloud Run instance for SSR), that runtime is bound to Google Cloud and can't move to Static Hosting. For static-export builds, you're good — keep reading.

What you'll build

By the end of this guide:

A Firebase Studio workspace synced to your own GitHub repository
A DeployHQ project with Static Hosting connected to that repo
A framework configured for static output (Next.js export, Vite build, Angular --configuration production, etc.)
A working build pipeline that runs your framework's build and uploads the output to Cloudflare's edge
Firebase Auth authorized domains updated to include the new URL
The site serving over HTTPS at <subdomain>.deployhq-sites.com (and optionally a custom domain)
Atomic deploys on every push to main, with one-click rollback to any previous version

Expected time: under 20 minutes from a Firebase Studio workspace you already have set up.

Prerequisites

A Firebase Studio workspace — created at firebase.studio — with a working frontend and a Firebase project providing whatever services it uses (Auth, Firestore, Storage, Functions)
A GitHub account you can sync the workspace to
Access to the Firebase project's console (you'll update Auth authorized domains in Step 7)
A DeployHQ account with beta features enabled (enable under Settings > Beta Features )
Node.js installed locally if you want to test the build before pushing (optional but recommended)

If you don't have a DeployHQ account yet, you can start a free trial in the next step — the trial includes one Static Hosting site at no charge while the feature is in beta.

Step 1: Sync your Firebase Studio workspace to GitHub

Firebase Studio runs your workspace in a Nix-based environment in the browser, with the source code stored in a Google Cloud workspace. To deploy on DeployHQ, the code needs to live in a normal Git repository.

In Firebase Studio:

Open the workspace you want to deploy
Open the Source Control panel from the left sidebar
Click Publish to GitHub (or Sync if you've already connected a repo)
Authorize Firebase Studio's GitHub integration if you haven't already
Choose a repository name and visibility, then publish

Firebase Studio commits the workspace contents — package.json, framework config files, src/, the dev.nix environment file under .idx/, and any Firebase configuration files (firebase.json, .firebaserc) — to the main branch of the new repository.

Open the repo in GitHub and confirm package.json is at the root. You'll identify the build command and output directory in the next step.

Step 2: Configure the framework for static output

Firebase Studio scaffolds projects across several frameworks. The right Static Hosting configuration depends on which template the workspace started from. Two things to verify: the build command and the output directory.

Framework	Default build command	Output directory	Static-ready out of the box?
Next.js (App Router)	`npm run build`	`out/`	No — set `output: 'export'` in `next.config.js`
Angular	`npm run build`	`dist/<project-name>/browser/`	Yes
Vite + React	`npm run build`	`dist/`	Yes
Vite + Vue	`npm run build`	`dist/`	Yes
Astro	`npm run build`	`dist/`	Yes
Flutter web	`flutter build web`	`build/web/`	Yes

For the Next.js case specifically, open next.config.js (or next.config.mjs) and add:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

This switches Next.js from SSR mode to a static export written to out/. Any code path using getServerSideProps, server actions, route handlers, or App Router server components will fail the build — those features need a runtime Static Hosting doesn't provide. The images.unoptimized: true flag disables Next.js Image Optimization, which also needs a server.

If your workspace uses firebase.json to define Firebase Hosting rewrites — single-page-app fallbacks, URL redirects, custom headers — those won't apply on DeployHQ. SPA rewrite is handled by Static Hosting's SPA mode (Step 4), and Cloudflare's edge handles HTTPS and caching headers automatically.

Step 3: Verify the Firebase configuration

Firebase Studio apps initialize the Firebase JS SDK with a config object usually pulled from environment variables (NEXT_PUBLIC_FIREBASE_* for Next.js, VITE_FIREBASE_* for Vite, process.env.NG_APP_FIREBASE_* for Angular).

Open the Firebase initialization file (src/lib/firebase.ts, src/firebase.ts, or wherever your workspace puts it) and confirm it reads from environment variables rather than hardcoded values. The relevant variables are:

*_FIREBASE_API_KEY — public API key (safe in client bundles)
*_FIREBASE_AUTH_DOMAIN — typically <project-id>.firebaseapp.com
*_FIREBASE_PROJECT_ID
*_FIREBASE_STORAGE_BUCKET
*_FIREBASE_MESSAGING_SENDER_ID
*_FIREBASE_APP_ID

These are all designed to be public — Firebase enforces security at the service level via Firestore Security Rules, Storage Rules, and Firebase Auth, not by hiding the config.

If your project calls Cloud Functions, the function URLs use the Firebase project's default domain (https://<region>-<project-id>.cloudfunctions.net or https://<custom-domain>.cloudfunctions.net). Those calls work from any frontend host as long as the function's CORS is configured to allow your origin (covered in Step 7 and the gotchas section).

Step 4: Provision a Static Hosting site in DeployHQ

In your DeployHQ project (or create one and connect it to the Firebase Studio repository), click New Server :

Enter a name for the server — internal reference only, doesn't affect the public URL
Select Static Hosting from the protocol picker under Hosting
Choose a subdomain — your site serves at <subdomain>.deployhq-sites.com. Subdomains are unique across all DeployHQ accounts; lowercase letters, numbers, and hyphens only
Set the subdirectory to deploy from to match your framework's output directory from Step 2 (out/, dist/, dist/<project-name>/browser/, or build/web/)
Toggle SPA mode based on your framework:
- On for Angular, Vite + React/Vue SPAs, Flutter web — these use client-side routing and need unknown paths rewritten to index.html
- Off for Next.js static export and Astro — these generate one HTML file per route at build time
Click Create Server

DeployHQ runs framework detection against the connected repository. If a [Framework] detected! callout appears with a suggested output directory and SPA mode, the rule-based detector is doing the work for you. Accept the suggested values unless your framework config diverges from the defaults.

Provisioning takes under a minute. Once the status flips to active, the site exists on Cloudflare's edge — but no code has shipped yet.

Step 5: Configure the build pipeline

DeployHQ runs your build before transferring artifacts to the edge. For a Firebase Studio-exported project, the build pipeline is two stages: install, then build.

In the project's build settings, add:

npm ci
npm run build

For Flutter, swap to the Flutter SDK install + flutter build web instead. For Angular projects with environment-specific builds, you may need npm run build -- --configuration production.

Environment variables to set in DeployHQ's environment-variable UI — the prefix depends on your framework:

Next.js : NEXT_PUBLIC_FIREBASE_API_KEY, NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN, etc.
Vite + React/Vue : VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, etc.
Angular : NG_APP_FIREBASE_API_KEY etc. (or environment.ts files if you're using the older pattern)

What you should not put here: Firebase Admin SDK service-account JSON, Firebase Functions deployment tokens, any credential that grants server-side access. Those belong in Cloud Functions runtime config, never in a static bundle.

If your project also uses third-party services (Stripe publishable keys, Sentry DSN, public analytics IDs), they go here too — same prefix rules apply.

Ready to take it live? Sign up free for DeployHQ if you don't have an account, and the beta-tier Static Hosting site is enough to ship this guide end to end.

Step 6: First deploy

Push any change to the configured branch (typically main), or trigger a manual deployment from the DeployHQ dashboard. DeployHQ:

Clones the repo at the head of the configured branch
Runs the build pipeline (npm ci && npm run build)
Uploads the contents of your output directory to object storage atomically
Flips Cloudflare's edge routing to serve the new version

The deployment log streams each step in real time. When it completes, visit https://<subdomain>.deployhq-sites.com — the site loads, but Firebase Auth won't yet allow sign-ins from the new domain. That's Step 7.

If the build fails, the log shows the exact error. Most common failures for Firebase Studio projects:

A Next.js page or route handler using a server-only feature without output: 'export' configured
A missing *_FIREBASE_* env var the client bundle references at build time
A firebase.json declaring a Cloud Functions rewrite the static export can't fulfill
An Angular project building without the production configuration, leaving development-only checks in the bundle

Fix the issue in the repo, commit, push — DeployHQ runs the next build automatically.

Step 7: Update Firebase Auth authorized domains

Firebase Auth has an allowlist of authorized domains — sign-in flows only work from domains on that list. Until your new domain is added, OAuth providers (Google, Facebook, GitHub) and email-link sign-ins will reject the authentication request.

In the Firebase Console:

Open the project that backs this app
Navigate to Authentication > Settings > Authorized domains
Click Add domain and enter <subdomain>.deployhq-sites.com (and any custom domain you'll add in Step 8)
Save

Existing entries like localhost, your old Firebase Hosting domain, and any previously configured custom domains stay on the list — Firebase Auth allows multiple authorized domains, so the Firebase Studio preview environment continues to work.

Sign out, sign back in on the new domain, and confirm the auth flow round-trips correctly.

Step 8: Add a custom domain

To serve from your own domain (e.g., app.example.com):

In your DNS provider, add a CNAME record pointing your subdomain to <subdomain>.deployhq-sites.com
Wait for DNS propagation (usually minutes; depends on your TTL)
Cloudflare provisions an HTTPS certificate automatically once the CNAME resolves
Add the custom domain to Firebase Auth's authorized domains list (same path as Step 7) so OAuth flows from app.example.com round-trip correctly

Your site now serves from app.example.com over HTTPS via Cloudflare's edge, talking to the same Firebase backend Firebase Studio scaffolded for you.

For an apex domain (example.com with no subdomain), use an ALIAS or ANAME record if your DNS provider supports them — Cloudflare DNS, DNSimple, and Route 53 all do. Otherwise, host the apex elsewhere and CNAME a www subdomain to DeployHQ.

Common gotchas

Firebase Studio App Hosting isn't supported. Firebase App Hosting is Firebase's newer SSR offering — it provisions a Cloud Run instance per deployment. That runtime is fundamentally Google-bound. If your workspace was scaffolded for App Hosting, you're locked into Firebase Hosting until you switch to a static-export configuration. Static Hosting is for static export only.

OAuth provider rejects the new domain. Google sign-in, Facebook sign-in, GitHub sign-in, and other federated providers have their own allowlists in addition to Firebase Auth's authorized domains list. Open each provider's app/credentials page (Google Cloud Console, Facebook Developers, GitHub OAuth Apps) and add the new Firebase Auth callback URL — usually https://<project-id>.firebaseapp.com/__/auth/handler — to the authorized redirect URIs. The error usually shows up as a redirect_uri_mismatch in the provider's response.

Cloud Functions return CORS errors. Cloud Functions enforce origin allowlists. Update the function's CORS configuration (typically via the cors package in your function source, or via Firebase Hosting rewrites that proxy through firebase.json — which doesn't apply here). For DeployHQ-hosted frontends, configure CORS directly in the function code to accept your new domain.

Firestore queries return empty results in production. Almost always a Firestore Security Rules mismatch. The Firebase Studio preview environment sometimes uses a different auth context. Check the rules on the affected collections and confirm they allow the production user's auth claims.

Build succeeds but environment variables don't appear in the bundle. Each framework requires a specific prefix at build time: Next.js needs NEXT_PUBLIC_*, Vite needs VITE_*, Angular reads from a separate environment.production.ts file by default. Double-check (a) the variable names match the prefix exactly, (b) you triggered a new build after setting them, and (c) for Angular, you're building with the production configuration.

firebase.json rewrites don't apply. Firebase Hosting's rewrites array configures the SPA fallback, URL redirects, and Cloud Function proxying. None of that runs on Static Hosting. Use DeployHQ's SPA mode for the SPA fallback. For Cloud Function proxying, point the frontend directly at the Cloud Function URL instead of relying on a /api/* rewrite.

Next.js next/image falls back to <img>. Static export disables Next.js Image Optimization. For better performance, pre-optimize at build time with sharp or next-export-optimize-images, or use an image CDN (Cloudflare Images, Imgix, Cloudinary).

What you've shipped

You now have:

A Firebase Studio frontend rebuilding on every push to main
Atomic deploys with no downtime during the transfer
HTTPS over Cloudflare's edge with automatic certificate management
One-click rollback to any previous deployment from the DeployHQ dashboard
Firebase Auth, Firestore, Storage, and Cloud Functions unchanged, doing exactly what they did before
A clean separation between the static UI and Google's backend services

For the broader context of how Static Hosting fits among DeployHQ's other hosting types, see the hosting hub. The Static Hosting pillar guide covers framework auto-detection, SPA mode, and the head-to-head against the most common alternatives. If you're weighing your hosting options more broadly, our DeployHQ Static Hosting vs Vercel comparison is a useful next read for the Next.js side of Firebase Studio projects.

What's next

If your Firebase Studio project outgrows static export — you need real SSR, server-rendered routes you can't move to client-side rendering, or a Node service that doesn't fit the Cloud Functions model — there are two clean upgrade paths inside the same DeployHQ project:

Move SSR rendering to DeployHQ Managed VPS and keep using Firebase services on the backend. The DeployHQ pipeline ships to either target; you swap the server type, not the project.
Split: keep Static Hosting for the public UI, run dynamic parts on Managed VPS or BYO server. The static frontend stays on Cloudflare's edge; the SSR layer runs elsewhere; Firebase services keep doing their thing.

Either path, the build pipeline you set up here continues to work — DeployHQ's build is generic, the target is what swaps.

Built your app with a different AI tool? Bolt, Lovable, and v0 export the same kind of static frontend, each with its own per-tool quirks — our free static hosting for AI-built apps roundup maps where each builder leaves you and how to host the result without lock-in.

For a roundup of how DeployHQ fits alongside the rest of the deployment-tool category, our best software deployment tools in 2026 post is a useful reference. And for context on the broader DeployHQ proposition across all five hosting types it supports, see your universal deployment and hosting platform.

If you're sizing what's included before signing up, the DeployHQ pricing page lays out which plan covers what — the beta-tier Static Hosting site is enough to ship this guide end to end. For the full product reference, see the Static Hosting support library.

Questions or feedback on deploying Firebase Studio apps to DeployHQ Static Hosting? Email support@deployhq.com or follow @deployhq on X for product updates.

How to Deploy a Bolt App to DeployHQ Static Hosting

DeployHQ — Fri, 19 Jun 2026 15:03:34 +0000

DeployHQ Static Hosting serves pre-built static assets from Cloudflare's global edge — exactly what a Bolt.new project produces when its frontend compiles. This guide walks through deploying a Bolt app end to end: export the project to GitHub, sanity-check the build output, provision the site in DeployHQ, configure the build pipeline, and ship the first deploy.

This is the static frontend path. Bolt starter templates often ship with a server/ directory running Express, Hono, or Fastify to handle data and auth — that code needs a Node runtime Static Hosting doesn't provide. If your Bolt app has a server, you have two clean options: run only the static frontend on Static Hosting and point it at your existing API, or use DeployHQ's Managed VPS option to host both the frontend and the Node server in one place. For purely client-side Bolt apps — landing pages, marketing sites, design demos, internal tools, prototypes, anything that talks to third-party APIs from the browser — Static Hosting is the cleanest fit.

What you'll build

By the end of this guide:

A Bolt.new project exported to your own GitHub repository
A DeployHQ project with Static Hosting connected to that repo
A working build pipeline that runs your framework's build command and uploads the output to Cloudflare's edge
The site serving over HTTPS at <subdomain>.deployhq-sites.com (and optionally a custom domain)
Atomic deploys on every push to main, with one-click rollback to any previous version

Expected time: under 15 minutes from a Bolt project you already have generated.

Prerequisites

A Bolt.new project — generated at bolt.new — that you're happy with
A GitHub account Bolt can push to
A DeployHQ account with beta features enabled (enable under Settings > Beta Features )
Node.js installed locally if you want to test the build before pushing (optional but recommended)

If you don't have a DeployHQ account yet, you can start a free trial in the next step — the trial includes one Static Hosting site at no charge while the feature is in beta.

Step 1: Export your Bolt project to GitHub

Bolt runs your project inside a StackBlitz WebContainer in the browser. To deploy it on DeployHQ, the code needs to live in a normal Git repository.

In Bolt:

Open the project you want to deploy
Click the GitHub icon in the top toolbar (or Export depending on your Bolt version)
Authorize Bolt to access your GitHub account if you haven't already
Choose a repository name and visibility, then push

Bolt commits the full project — package.json, framework config files, src/, public/, and any .bolt/ metadata directory — to the main branch of the new repository.

Open the repo in GitHub and confirm package.json is at the root. You'll use it to identify the build command and output directory in the next step.

Step 2: Identify the framework and output directory

Bolt projects are framework-agnostic. The right Static Hosting configuration depends on which framework Bolt scaffolded for you. The build output directory is what matters — Static Hosting uploads the contents of that directory to the edge.

Framework	Default build command	Output directory
Vite + React	`npm run build`	`dist/`
Vite + Vue	`npm run build`	`dist/`
Vite + Svelte	`npm run build`	`dist/`
Astro	`npm run build`	`dist/`
SvelteKit (adapter-static)	`npm run build`	`build/`
Next.js (static export)	`npm run build`	`out/`
Remix (with static adapter)	`npm run build`	`build/client/`

Open package.json and confirm the build script matches what's in the table. Open the framework config (e.g., vite.config.ts, astro.config.mjs, next.config.js) and note any custom output directory if it's been overridden.

If your Bolt project is a Next.js starter, ensure output: 'export' is set in next.config.js — Bolt's default Next.js scaffold assumes a Node runtime. The Next.js deployment guide covers the full static-export configuration.

If your project includes a server/ directory (Express, Hono, Fastify, etc.), that code won't run on Static Hosting — make sure none of your frontend code depends on those endpoints at runtime, or refactor those calls to hit a separate API.

Step 3: Provision a Static Hosting site in DeployHQ

In your DeployHQ project (or create one and connect it to the Bolt repository), click New Server :

Enter a name for the server — internal reference only, doesn't affect the public URL
Select Static Hosting from the protocol picker under Hosting
Choose a subdomain — your site serves at <subdomain>.deployhq-sites.com. Subdomains are unique across all DeployHQ accounts; lowercase letters, numbers, and hyphens only
Set the subdirectory to deploy from to match your framework's output directory from Step 2 (dist/, out/, build/, or build/client/)
Toggle SPA mode based on your framework:
- On for Vite + React SPA, Vite + Vue SPA, Vite + Svelte SPA — these single HTML files use client-side routing and need unknown paths rewritten to index.html
- Off for Astro, SvelteKit static, and Next.js static export — these generate one HTML file per route at build time
Click Create Server

Provisioning takes under a minute. Once the status flips to active, the site exists on Cloudflare's edge — but no code has shipped yet.

Step 4: Configure the build pipeline

DeployHQ runs your build before transferring artifacts to the edge. For a Bolt-exported project, the build pipeline needs two stages: install, then build.

In the project's build settings, add:

npm ci
npm run build

If your package.json declares pnpm or yarn as the package manager (Bolt sometimes does, especially for monorepo-style starters), swap to pnpm install --frozen-lockfile or yarn install --frozen-lockfile.

Environment variables to set in DeployHQ's environment-variable UI:

Public-prefixed env vars your framework inlines into the static bundle (Vite: VITE_*, Next.js: NEXT_PUBLIC_*, Astro: PUBLIC_*)
NODE_ENV=production — usually set automatically but worth confirming for deterministic builds

Anything that isn't prefixed for client exposure stays out of the bundle — that's the framework's standard behavior, not a Static Hosting limitation. If your Bolt project talks to Supabase, Stripe (publishable key), or a third-party API, the URLs and public keys go here. Service-role keys, secret API tokens, and database credentials never belong in a static build.

Ready to take it live? Sign up free for DeployHQ if you don't have an account, and the beta-tier Static Hosting site is enough to ship this guide end to end.

Step 5: First deploy

Push any change to the configured branch (typically main), or trigger a manual deployment from the DeployHQ dashboard. DeployHQ:

Clones the repo at the head of the configured branch
Runs the build pipeline (npm ci && npm run build)
Uploads the contents of your output directory to object storage atomically
Flips Cloudflare's edge routing to serve the new version

The deployment log streams each step in real time. When it completes, visit https://<subdomain>.deployhq-sites.com and confirm the site renders.

If the build fails, the log shows the exact error. Most common failures for Bolt-exported projects:

A starter template that includes a server/ directory the frontend code depends on at build time
Hardcoded paths starting with /home/project/ left over from the WebContainer environment
A missing dependency the package.json declares but Bolt didn't ship a lockfile entry for
Framework-specific config overrides (custom outDir, base, or publicPath) the build pipeline doesn't know about

Fix the issue in the repo, commit, push — DeployHQ runs the next build automatically.

Step 6: Add a custom domain

To serve from your own domain (e.g., app.example.com):

In your DNS provider, add a CNAME record pointing your subdomain to <subdomain>.deployhq-sites.com
Wait for DNS propagation (usually minutes; depends on your TTL)
Cloudflare provisions an HTTPS certificate automatically once the CNAME resolves

Your site now serves from app.example.com over HTTPS via Cloudflare's edge.

Common gotchas

The build pulls in server/ files. Bolt full-stack starter templates expect the server and client to coexist. If your vite.config.ts or framework config includes a path alias pointing into server/, the build will try to bundle Node-only modules and fail. Either remove the alias for a pure frontend deployment, or move the server to DeployHQ Managed VPS.

Hardcoded WebContainer paths. Bolt sometimes leaves /home/project/ paths in generated code, especially in scripts or test fixtures. These break in any environment that isn't a WebContainer. Search the repo for /home/project/ and replace with relative paths or process.cwd().

Build succeeds but the page is blank. Vite + React SPAs often need base: '/' set explicitly in vite.config.ts when deployed at the root. If you're deploying under a subpath, set base: '/subpath/' to match. Check the browser console — a 404 on /assets/index-*.js is the giveaway.

Tailwind classes missing in production. Bolt's Vite scaffold sometimes uses content paths that miss files in nested directories. Verify tailwind.config.ts includes every path your components actually live under — ./src/**/*.{js,ts,jsx,tsx,vue,svelte} covers the standard layout, but Bolt's project structure can vary.

Routes 404 on direct page load (Vite SPA). This is SPA mode not being enabled in DeployHQ. Toggle it on — Static Hosting will rewrite unknown paths to index.html so client-side routing takes over.

Supabase auth callback fails. If your Bolt app uses Supabase and the auth callback URL points to a /auth/callback route handler, it'll 404 because that route handler can't run on Static Hosting. Move the auth-callback logic into client-side code that reads the URL hash, or run the callback handler on a separate backend.

What you've shipped

You now have:

A Bolt project rebuilding on every push to main
Atomic deploys with no downtime during the transfer
HTTPS over Cloudflare's edge with automatic certificate management
One-click rollback to any previous deployment from the DeployHQ dashboard
Predictable, free hosting while Static Hosting is in beta

For the broader context of how Static Hosting fits among DeployHQ's other hosting types, see the hosting hub. The Static Hosting pillar guide covers framework auto-detection, SPA mode, and the head-to-head against the most common alternatives. Since Bolt ships with a one-click Netlify deploy button, the DeployHQ Static Hosting vs Netlify comparison is directly relevant when you're choosing where to host outside the built-in option.

What's next

If your Bolt project outgrows static export — you need to run the server/ directory in production, add real auth, or handle dynamic data without a separate backend — there are two clean upgrade paths inside the same DeployHQ project:

Move to DeployHQ Managed VPS and run the full Node app — both your frontend bundle and your server/ code in one place. The DeployHQ pipeline ships to either target; you swap the server type, not the project.
Split: keep Static Hosting for the UI, run the server/ directory elsewhere. A separate Managed VPS or BYO server hosts the API, and the static frontend stays on Cloudflare's edge.

Either path, the build pipeline you set up here continues to work — DeployHQ's build is generic, the target is what swaps.

Questions or feedback on deploying Bolt projects to DeployHQ Static Hosting? Email support@deployhq.com or follow @deployhq on X for product updates.

How to Deploy a v0 App to DeployHQ Static Hosting

DeployHQ — Thu, 18 Jun 2026 05:45:50 +0000

DeployHQ Static Hosting runs static builds on Cloudflare's global edge — exactly the shape v0 produces when you export a project as a Next.js codebase. This guide walks through deploying a v0 app end to end: export the project to GitHub, provision the site in DeployHQ, configure the build pipeline, and ship the first deploy.

This is the static-export path. If your v0 project uses Next.js server actions, App Router server components, or any backend route handlers, Static Hosting can't run that code — those parts need a Node runtime on DeployHQ's Managed VPS option, a separate serverless layer, or an existing API you call from the client. For purely static UI — marketing pages, landing pages, design demos, internal tools, prototypes — Static Hosting is the cleanest fit.

What you'll build

By the end of this guide:

A v0 project exported to your own GitHub repository
A DeployHQ project with Static Hosting connected to that repo
A working build pipeline that runs next build (with static export) and uploads the output to Cloudflare's edge
The site serving over HTTPS at <subdomain>.deployhq-sites.com (and optionally a custom domain)
Atomic deploys on every push to main, with one-click rollback to any previous version

Expected time: under 15 minutes from a v0 project you already have generated.

Prerequisites

A v0 project — generated at v0.app — that you're happy with
A GitHub account v0 can push to
A DeployHQ account with beta features enabled (enable under Settings > Beta Features )
Node.js installed locally if you want to test the build before pushing (optional but recommended)

If you don't have a DeployHQ account yet, you can start a free trial in the next step — the trial includes one Static Hosting site at no charge while the feature is in beta.

Step 1: Export your v0 project to GitHub

v0 generates Next.js code. To deploy it anywhere outside v0's built-in Vercel target, you need the code in your own repository.

In v0:

Open the project you want to deploy
Click the GitHub icon in the project toolbar (or Export → GitHub depending on your v0 version)
Authorize v0 to access your GitHub account if you haven't already
Choose Create new repository and pick a name, or Push to existing repository if you've already exported once
Confirm the push

v0 commits the full Next.js project — app/, components/, package.json, next.config.js, tailwind.config.ts, and the rest — to the main branch of the repository you selected.

Open the repo in GitHub and confirm next.config.js (or next.config.mjs) is present. You'll edit it in the next step.

Step 2: Configure Next.js for static export

v0's generated next.config.js is set up for Vercel by default, which assumes a Node runtime. Static Hosting needs the export build instead.

Edit next.config.js to add output: 'export' and disable Next.js Image Optimization (it requires a server):

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

A few things this changes:

next build writes a static export to out/ instead of starting a Node server
Any route using getServerSideProps, server actions, route handlers, or middleware will fail the build — those features need a runtime Static Hosting doesn't provide
next/image falls back to plain <img> rendering — no on-the-fly resizing

Commit and push the change:

git add next.config.js
git commit -m "Configure Next.js for static export"
git push origin main

Optionally, run npm install && npm run build locally first to catch any server-only code paths v0 emitted before DeployHQ runs the same build.

Step 3: Provision a Static Hosting site in DeployHQ

In your DeployHQ project (or create one and connect it to the v0 repository), click New Server :

Enter a name for the server — internal reference only, doesn't affect the public URL
Select Static Hosting from the protocol picker under Hosting
Choose a subdomain — your site serves at <subdomain>.deployhq-sites.com. Subdomains are unique across all DeployHQ accounts; lowercase letters, numbers, and hyphens only
Set the subdirectory to deploy from to out (the default Next.js static export directory)
Leave SPA mode off — Next.js static export generates one HTML file per route, so client-side routing fallbacks aren't needed
Click Create Server

DeployHQ runs framework detection against the connected repository. If a Next.js detected! callout appears, the rule-based detector picked up your next.config.js. Accept the suggested values for a stock v0 export.

Provisioning takes under a minute. Once the status flips to active, the site exists on Cloudflare's edge — but no code has shipped yet.

Step 4: Configure the build pipeline

DeployHQ runs your build before transferring artifacts to the edge. For a v0-exported Next.js project, the build pipeline needs two stages: install, then build.

In the project's build settings, add:

npm ci
npm run build

If v0 emitted a pnpm-lock.yaml or yarn.lock instead of package-lock.json, swap to pnpm install --frozen-lockfile or yarn install --frozen-lockfile accordingly.

Environment variables to set in DeployHQ's environment-variable UI:

NEXT_PUBLIC_* — any public env vars Next.js inlines into the static bundle (API base URLs, public keys, feature flags)
NODE_ENV=production — usually set automatically but worth confirming for deterministic builds

Anything not prefixed with NEXT_PUBLIC_ will not appear in the static bundle — that's Next.js's standard behavior, not a Static Hosting quirk.

If your v0 project hits external APIs (Supabase for auth, a database backend, third-party services), the URLs and public keys go here. Secrets that should never reach the client — service-role keys, private API tokens — stay out of the static build entirely.

Ready to take it live? Sign up free for DeployHQ if you don't have an account, and the beta-tier Static Hosting site is enough to ship this guide end to end.

Step 5: First deploy

Push any change to the configured branch (typically main), or trigger a manual deployment from the DeployHQ dashboard. DeployHQ:

Clones the repo at the head of the configured branch
Runs the build pipeline (npm ci && npm run build)
Uploads the contents of out/ to object storage atomically
Flips Cloudflare's edge routing to serve the new version

The deployment log streams each step in real time. When it completes, visit https://<subdomain>.deployhq-sites.com and confirm the site renders.

If the build fails, the log shows the exact error. Most common failures for v0 exports:

A page or route handler v0 generated that uses a server-only feature (server actions, getServerSideProps)
next/image used without unoptimized: true
A missing dependency v0's package.json declares but didn't ship with a lockfile entry

Fix the issue in the repo, commit, push — DeployHQ runs the next build automatically.

Step 6: Add a custom domain

To serve from your own domain (e.g., app.example.com):

In your DNS provider, add a CNAME record pointing your subdomain to <subdomain>.deployhq-sites.com
Wait for DNS propagation (usually minutes; depends on your TTL)
Cloudflare provisions an HTTPS certificate automatically once the CNAME resolves

Your site now serves from app.example.com over HTTPS via Cloudflare's edge.

Common gotchas

Server actions fail at build. v0 sometimes generates form submissions as server actions. Static export can't run server code at request time, so those builds break. Refactor server actions into client-side fetches that hit a separate API (your existing backend, a Cloudflare Worker, Supabase, etc.).

Route handlers (app/api/*) don't work. Same root cause — they need a Node runtime. Move that logic to a separate backend, or call third-party APIs directly from the client when the keys are public.

Images render but look unoptimized. next/image skips its optimization pipeline under unoptimized: true. For better performance, pre-optimize at build time with sharp or next-export-optimize-images, or use an image CDN (Cloudflare Images, Imgix, Cloudinary).

Build succeeds but routes 404 on the live site. v0 dynamic routes ([slug].tsx) need generateStaticParams to enumerate which paths to render at build time. Without that, the export skips the dynamic routes entirely. Add generateStaticParams returning the list of slugs you want pre-rendered.

Tailwind classes missing in production. v0 occasionally generates class names that Tailwind's content scanner misses. Double-check tailwind.config.ts includes every path your components live under — ./app/ **/*.{js,ts,jsx,tsx,mdx} and ./components/** /*.{js,ts,jsx,tsx,mdx} cover most v0 projects.

Trailing slashes change URLs mid-project. If you add trailingSlash: true to next.config.js after the first deploy, every route URL changes. Set it intentionally at the start, or commit to a redirect plan if you switch.

What you've shipped

You now have:

A v0 project rebuilding on every push to main
Atomic deploys with no downtime during the transfer
HTTPS over Cloudflare's edge with automatic certificate management
One-click rollback to any previous deployment from the DeployHQ dashboard
Predictable, free hosting while Static Hosting is in beta

For the broader context of how Static Hosting fits among DeployHQ's other hosting types, see the hosting hub. The Static Hosting pillar guide covers framework auto-detection, SPA mode, and the head-to-head against the most common alternatives — including our DeployHQ Static Hosting vs Vercel comparison, which is directly relevant for v0 users weighing where to host outside Vercel itself.

For the full Next.js side of the workflow, the Next.js deployment guide goes deeper on configuration choices that apply equally to v0-exported projects.

What's next

If your v0 project outgrows static export — you add real auth, dynamic data, or server actions you can't refactor away — there are two clean upgrade paths inside the same DeployHQ project:

Move to DeployHQ Managed VPS and run a full Next.js Node process. The DeployHQ pipeline you built ships to either target; you swap the server type, not the project.
Split: keep Static Hosting for the UI, run dynamic parts elsewhere. A separate Managed VPS or BYO server handles the API/SSR, and the static frontend stays on Cloudflare's edge.

Either path, the build pipeline you set up here doesn't change.

Questions or feedback on deploying v0 projects to DeployHQ Static Hosting? Email support@deployhq.com or follow @deployhq on X for product updates.

DEV Community: DeployHQ

DeployHQ Managed VPS vs Render: Real Linux vs PaaS Sandbox

TL;DR

At a glance: feature comparison

When DeployHQ Managed VPS is the right choice

When Render is the right choice

Pricing: side by side

Moving between them (it's not all-or-nothing)

The real Linux vs PaaS trade-off

FAQ

Get started

Using Claude Code with SQLite: The Safest Way to Prototype Queries Locally

Why SQLite is the right place to start

Pointing Claude Code at a .sqlite file

Why a file is the safest sandbox you can give an AI

Exploring schema and prototyping queries

When to graduate from SQLite

Moving validated queries into a real deployment

Running AI Coding Agents in CI/CD: Claude Code, Codex, and Gemini CLI in Headless Mode

Headless Mode for Each CLI

Claude Code

Codex CLI

Gemini CLI

Practical Use Cases with Full CI Config

1. Auto-Generate Changelog from Git Diff

2. AI-Powered Code Review on Changed Files

3. Auto-Fix CI Failures

4. Security Scanning with AI Triage

5. Generate Tests for Modified Code

Other CI Platforms

Connecting to Deployment

Cost Management

Security Considerations

When to Use What

Managing Secrets: .env Files, .env.example, and Config in DeployHQ

What Is a .env File?

The KEY=VALUE Format

How Different Frameworks Load .env Files

Node.js

Python

Ruby

PHP

Security Best Practices

Never Commit .env to Version Control

Use .env.example as a Template

Restrict File Permissions

Environment-Specific Files

Common Patterns and Gotchas

Variable Expansion

Multiline Values

Boolean Values

Configuring Secrets in DeployHQ: UI, CLI, and API

Config Files vs Environment Variables

The UI Method

The CLI Method

The API Method

Which One Should You Use?

FAQ

Project Folders Are Here: Group Deployments by Client, Team, or Environment

What project folders actually do

Why this matters for agencies and freelancers

Setting up folders in a couple of clicks

Ungrouped as an intake lane

Permissions: let a lead own the structure

Take it further: team management for scoped access

Automating folders through the API

A small feature that scales with you

Self-Host Vaultwarden (Bitwarden) on a VPS with Docker

Why self-host Vaultwarden

Why Docker

Prerequisites

The Compose stack

TLS via Caddy

First-run: create your account, lock the door

Push notifications for mobile clients

Backups: the part nobody covers

Operational concerns

Continuous deployment with DeployHQ

Wrapping up

How to Let AI Query Your Database Without Deleting It: Read-Only Guardrails for Claude Code

Pointing Claude Code at a `.sqlite` file