Test a branch before you merge

Put the branch your AI tool is working on at its own address. Try it, then merge.

When a coding agent works on a branch, you want to see the change running before you merge it. The Dockhold CLI can give that branch its own app at its own URL, next to the app you already run. All it takes is a second checkout of your repository and one command.

Before you start

Node 18 or newer, and the CLI signed in once with npx dockhold login. See Deploy from your computer.
Room for one more app. The free plan runs one app. A second app needs compute, added under Usage & billing in the dashboard sidebar: $5 a month adds 512 MB. See pricing.

1. Check the branch out in a worktree

A worktree is a second folder of the same repository, checked out on another branch. Claude Code, Codex and other coding agents can make one for you. To make one yourself, run this from your project folder:

git worktree add ../myapp-login login

That checks out the existing branch login into the folder ../myapp-login. Add -b before the branch name to start a new branch instead.

2. Deploy the worktree as its own app

cd ../myapp-login
npx dockhold deploy --name myapp-login --env API_URL=https://api.example.com

The first deploy from a folder creates a new app and remembers it in .dockhold/app.json inside that folder. Your main folder keeps its own app, so the branch never touches it. Name the app after the branch so you can tell them apart. The command waits until the app is live and prints its address.

The branch app starts with none of your main app's variables or secrets. Pass each variable with --env KEY=VALUE on this first deploy. .env files are never uploaded.

3. Change it and deploy again

The app does not follow new commits on the branch. After each change, run the same command again from the worktree:

npx dockhold deploy

It uploads the folder as it is on disk, committed or not, and updates the same app at the same address. Your main app stays as it was.

--name and --env only count on the first deploy, when the app is created. To change a variable later, edit it on the app's Variables tab and click Restart.

4. Merge, then remove the app

The branch app keeps running, and keeps using compute, until you delete it. Once the branch is merged, open the app in the dashboard, go to its Settings tab and click Delete this app. Then remove the worktree:

git worktree remove ../myapp-login

Keep `.dockhold/` out of git

On the first deploy the CLI adds .dockhold/ to your .gitignore, if the folder has one. Commit that line. If .dockhold/app.json ever gets committed, every new worktree checks out your main app's record, and a deploy from the branch replaces your main app. No .gitignore yet? Create one that lists .dockhold/.

Ask your AI tool

Paste this into your coding agent when its branch is ready to try:

Put this branch online so I can test it before merging. In this
worktree, run: npx dockhold deploy --name <app>-<branch>
Pass every variable the app needs with --env KEY=VALUE.
Then give me the address it prints.

Good to know

The branch app is a separate app. It shares no variables, secrets or database with your main app. Add --db on the first deploy for a database of its own. It starts empty and takes its storage from your pool.
App names use letters, digits and dashes. A slash in a branch name is dropped, so feature/login becomes featurelogin.
Everything else about the upload (what is left out, the size cap, how the folder is built) is in Deploy from your computer.