Claude Code Deployment: Production Guide

Claude Code deployment becomes reliable only when the agent can distinguish “request accepted” from “production is healthy.” Dockup provides that deployment layer through a CLI designed for machine callers: structured JSON, real process exit codes, and a --wait mode that stays attached until a deployment reaches a terminal state.

This guide takes a repository from local work to a verified production release. It also defines the permissions Claude Code should receive, the evidence it should return, and the point where a human must approve a destructive action.

What does Claude Code deployment need before production?

A coding agent should not begin by guessing a service name or clicking through a dashboard. Give it a narrow operating contract: discover the exact target, make one intended change, wait for the result, and report machine-readable evidence.

The basic prerequisites are straightforward:

Requirement	Why it matters	Verification
Node.js 18 or newer	Required by the Dockup CLI package	node --version
Dockup account	Owns workspaces, services, and databases	Sign in at app.dockup.ai
Git repository	Source for the service build	Confirm the remote URL and branch
API token	Non-interactive authentication	dockup whoami --json
Health endpoint or listening port	Gates the blue-green cutover	dockup health ... --json

Decide the production boundary before the agent acts. Claude Code may create a service, set non-secret configuration, trigger a deploy, inspect logs, and propose a rollback. It should not delete a service, remove a database, or prune configuration without explicit human approval.

Dockup reinforces that boundary. Destructive commands refuse to proceed without --yes and return a structured needs_confirm error instead of treating missing confirmation as an invitation to improvise. For a broader policy, use the production guardrails for AI agents.

How do you install the Claude Code skill and authenticate safely?

Install the CLI, install the bundled skill, and verify that the skill matches the installed binary:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

The installer writes the canonical skill to ~/.agents/skills/dockup/ and links it into Claude Code’s skill directory. Because the skill ships in the same npm package as the CLI, dockup update refreshes both. Claude Code does not have to rely on a copied command reference that may describe flags its local binary does not support.

Use an environment token for autonomous sessions:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

A successful response identifies the account and reports tokenSource as env. Do not paste the token into a prompt, commit it to the repository, or echo it in a CI log. Secret values stored in Dockup are masked when configuration is read back.

The complete Dockup CLI reference is the authoritative command surface. With 135 commands, Claude Code should consult the current reference and packaged skill rather than rely on remembered flags.

Because the skill ships inside the CLI package, dockup update refreshes the executable and its instructions together. This version alignment is safer than copying a command list into a long-lived prompt.

How does the Dockup CLI create a service from Git?

First ask the agent to identify the workspace and avoid constructing slugs from display names. Existing targets are returned by:

dockup services --json

For a repository that has never been deployed, one transaction can create the service, deploy it, wait for completion, and link the current directory:

dockup create my-api \
  --repo https://github.com/acme/my-api \
  --project production \
  --deploy \
  --wait \
  --link \
  --json

When the repository contains a Dockerfile, Dockup uses it. Without one, Dockup falls back to Nixpacks for automatic build detection. The choice is explained in Nixpacks vs Dockerfile, including when explicit build instructions are worth the maintenance cost.

Before retrying creation after an interrupted session, run dockup services --json again and inspect the exact target. If the service already exists, continue from its status instead of issuing another create request.

Once linked, commands in that repository can resolve the target from .dockup, but production runbooks should still record the full project/service value. Discovery is the safe boundary between an uncertain previous action and a new production mutation.

How should environment variables, databases, and health checks be prepared?

Keep ordinary configuration separate from secrets. Claude Code can set a public runtime value and a masked secret without printing stored secret values later:

dockup env set NODE_ENV=production \
  -s production/my-api \
  --json

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

Environment changes apply on the next deployment. That is intentional: a running container keeps its current process environment until it is replaced. The complete operating pattern is covered in environment variables and secrets.

If the application needs a managed PostgreSQL database, create it in the selected workspace and read its details through the documented database commands:

dockup db create --name main-db --type postgresql --json
dockup db list --json

Private networking can later give services and databases stable <slug>.internal hostnames inside one project. Do not have the agent invent a database URL; use the connection information returned by Dockup and store it as a secret.

Configure a readiness gate before the first important production release:

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

Dockup performs zero-downtime blue-green deployment and only cuts traffic to the new version after the health gate passes. The architecture is explored in zero-downtime deployments.

How does Claude Code deploy and prove that it succeeded?

Use --wait; do not let the agent interpret “deployment queued” as “application running”:

dockup deploy production/my-api --wait --json

The default wait timeout is 900 seconds. On success, the command exits 0 and returns the terminal status, duration, deployment ID, and URL. If the build fails, it exits non-zero with code:"deploy_failed". If the operation is still running at the timeout, it exits non-zero with code:"deploy_timeout".

A useful Claude Code instruction is: “Treat the process exit code as the primary result; then summarize the JSON fields.” That prevents optimistic language when the platform has already returned a failure.

After success, collect three independent signals:

dockup status production/my-api --json
dockup uptime production/my-api --hours 24 --json
dockup security production/my-api --json

status confirms the service and latest deployment state. uptime returns minute-by-minute monitoring statistics, including average response time and p95. security shows the latest image CVE and configuration scan. These checks complement application-level security practices; they do not replace application tests.

What should Claude Code do when production fails?

Separate build failure from runtime failure. A failed build requires the latest build log:

dockup logs production/my-api --build --json

A container that built but crashes after startup requires runtime output:

dockup logs production/my-api --json

To watch a build while preserving machine-readable batches, use NDJSON follow mode:

dockup logs production/my-api --build -f --json

The command stops when the deployment reaches a terminal state and exits non-zero if it failed. Claude Code can stream progress without inventing a polling loop.

If the current release is unhealthy and a known previous deployment should be rerun, list history and use its exact ID:

dockup deployments production/my-api -n 20 --json
dockup rollback <deploymentId> production/my-api --json

The agent should report which deployment ID it selected and why. Rollback is an operational decision, not a substitute for understanding the failure. Preserve the build log, runtime log, exit code, and audit record so the incident remains reconstructable.

A finished Claude Code deployment report should include the target, commit or branch, deployment ID, terminal status, URL, elapsed time, health result, and any follow-up risk. That evidence turns an autonomous action into a reviewable production change.

Define a production completion contract

Before starting, put the expected completion contract in the task. A useful request is: deploy the linked repository to production/my-api; wait for a terminal result; do not delete, prune, or transfer anything; on failure, return the error code and the final 60 relevant build-log lines; on success, return status, URL, deployment ID, duration, and health evidence.

This wording gives Claude Code a bounded objective and a reporting schema. It also prevents the agent from “helpfully” changing unrelated infrastructure when the release fails. The agent can propose a separate fix, but the production action remains attributable to one request.

For repeated releases, keep a small release record in the repository or change-management system. Record the target, source branch, expected health path, normal timeout, and approved recovery action. A Claude Code deployment is safer when the next session does not have to reconstruct these facts from chat history.

Verify the account boundary before the first write

Workspaces are ownership and billing boundaries. Ask Claude Code to show whoami, list services, and state the selected workspace before it mutates anything. The Go plan is $20 per month with $20 in usage credit and is the recommended paid plan; all paid plans permit unlimited workspaces, databases, and deployments, while CPU, RAM, and disk use are measured per minute against the plan balance.

That pricing model does not change the safety rule: an agent should inspect usage and target scope before scaling or creating additional resources. The production report should distinguish the subscription plan from actual metered consumption.

Put the workflow into production

Install the skill in the same environment where Claude Code will run, verify authentication, and begin with a low-risk service whose health endpoint is already known.

npm install -g dockup-cli
dockup skill install

The first command installs the CLI. The second installs the matching Dockup skill for Claude Code and Codex. Start free at app.dockup.ai.

FAQ

Can Claude Code deploy directly to production with Dockup?

Yes. Install the Dockup skill, provide a scoped DOCKUP_TOKEN, resolve the exact project/service target, and run the deploy command with --wait and --json.

Why should Claude Code use --wait?

Without --wait, a successful response only means the deployment was queued. With --wait, Dockup exits 0 only after success and returns structured deploy_failed or deploy_timeout errors otherwise.

Does Claude Code see stored secret values?

Dockup masks secret values in output. The agent can set or replace a secret, but reading environment configuration does not return the stored secret value.

What happens when a repository has no Dockerfile?

Dockup uses Nixpacks to detect and build the application automatically. A repository Dockerfile takes precedence when present.

How can Claude Code recover from a bad release?

It should inspect build and runtime logs, list deployment history, and rerun a known previous deployment with dockup rollback using the exact deployment ID.