Codex Deployment: End-to-End Dockup Workflow

A Codex deployment should end with evidence, not an assumption. The practical challenge is not asking Codex to run a deploy command; it is giving the agent an interface that identifies the exact target, waits for a terminal state, returns real exit codes, and exposes failure details without a browser.

Dockup is the deployment layer for this workflow. Its CLI gives Codex structured JSON on every supported command, and its bundled skill teaches the agent how to authenticate, discover services, deploy, diagnose, and stop before destructive operations.

How do you install the Codex CLI skill?

Install the CLI globally, then run the single skill installer. It writes the canonical skill and links it into both Claude Code and Codex:

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

The canonical skill lives at ~/.agents/skills/dockup/ and is symlinked into ~/.codex/skills/. It ships inside dockup-cli, so a normal update changes the executable and its instructions together:

dockup update

This version coupling matters in a large command surface. An agent should never execute a remembered flag just because it appeared in an old prompt. Codex should use the packaged skill and the current Dockup CLI reference as its command authority.

For the design rationale behind skills, see agent skills vs MCP.

How does Codex authenticate without an interactive terminal?

A sandbox or CI job may not be able to complete browser-based login. Set a token in the process environment:

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

DOCKUP_TOKEN takes precedence over the local config file. The whoami response reports whether the active credential came from the environment or config, which helps Codex diagnose the common case where a stale local token and a CI token coexist.

Treat the token as an infrastructure secret. Do not put it in AGENTS.md, SKILL.md, source control, command examples committed to the repository, or the agent’s final transcript. In CI, use the platform’s encrypted secret store and expose the value only to the deployment step. The full non-interactive pattern is detailed in CI/CD with DOCKUP_TOKEN.

Before giving Codex write access, decide its permission envelope. A reasonable initial scope includes service discovery, deployment, log reading, and status checks. Database deletion, service destruction, team changes, and config pruning should remain approval-gated.

How does Codex find or create the correct service?

Make discovery the first operation. Do not ask Codex to transform “Payments API” into a guessed slug:

dockup services --json

Each result includes an exact target in project/service form. Codex should copy that value into subsequent commands and return it in its summary.

When no service exists, create one from Git:

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

The command creates the service, deploys it, blocks until the deployment resolves, and writes a .dockup link in the working directory. A Dockerfile is used when present; otherwise Nixpacks performs automatic build detection.

When Codex loses session state or a workflow is rerun after a network interruption, it should rediscover services and inspect the exact target before mutating anything. If the target already exists, continue from its status and deployment history instead of issuing another create request.

The complete repository-first sequence is available in Git repository to production.

How should Codex prepare configuration before deploying?

Ask Codex to inspect current service metadata before changing it:

dockup info production/payments-api --json
dockup env list -s production/payments-api --json

The environment response includes keys and isSecret markers, while secret values remain masked. Codex can add ordinary variables and secrets separately:

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

dockup env set STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  --secret \
  -s production/payments-api \
  --json

Never put a production secret in dockup.yaml; the manifest is suitable for reviewable plain configuration, not credentials. Existing secret variables are not overwritten or pruned by the config-as-code workflow.

Configure the service’s listening port and readiness check when they are known:

dockup set production/payments-api --port 3000 --json
dockup health production/payments-api \
  --path /health \
  --interval 5 \
  --retries 5 \
  --json

A readiness gate makes the production verification meaningful. The platform performs a blue-green deployment and routes traffic only after the new version satisfies the gate.

How does production verification confirm the terminal state?

For an existing service, use one command:

dockup deploy production/payments-api \
  --wait \
  --timeout 900 \
  --json

The explicit timeout matches the default 900 seconds and makes the workflow intention visible. Exit 0 means the deployment succeeded. A non-zero result with deploy_failed means the build or deploy reached failure. deploy_timeout means the operation was still non-terminal when the wait period ended.

The correct Codex branching logic is based on the process status:

Result	Codex action
Exit 0, status:"success"	Continue to health, uptime, and security verification
deploy_failed	Read build logs and identify the first actionable error
deploy_timeout	Report uncertainty; inspect status or retry with a justified timeout
not_logged_in	Stop and request a valid token
needs_confirm	Stop and ask for human approval

After a successful Codex deployment, gather observable evidence:

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

Uptime checks run every minute and include response-time statistics such as p95. Security results include image CVEs and configuration checks. These signals do not prove business correctness, so Codex should also run the repository’s own smoke tests when they are available.

How should Codex diagnose and recover from a failed release?

Build errors and runtime errors require different logs. Use the latest build output when the deployment never reached a runnable container:

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

Use runtime logs when the image built but the application crashes, binds the wrong port, or fails after startup:

dockup logs production/payments-api --json

Follow mode is useful during a long build:

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

In JSON mode, follow output is NDJSON, allowing Codex to process each batch as it arrives. The stream ends at a terminal deployment state and preserves the real failure exit code.

Recovery starts with history, not a guessed rollback target:

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

Codex should identify a known successful deployment, state the selected ID, and preserve the failure evidence before rerunning it. It should never choose “the second item” without verifying status and timestamps.

A useful final report has seven fields: target, branch or commit, deployment ID, exit code, terminal status, production URL, and follow-up actions. That format makes each Codex deployment reviewable by a person or a later automation step.

A compact verification script

This shell pattern keeps deployment and diagnosis in one transparent control flow:

if dockup deploy production/payments-api --wait --json > deploy-result.json; then
  dockup status production/payments-api --json
  dockup uptime production/payments-api --hours 24 --json
else
  dockup logs production/payments-api --build --json
  exit 1
fi

The script does not grep for a success sentence. It trusts the CLI exit code, retains the deployment JSON, and fails the calling job when production did not reach success.

Make retries observable rather than invisible

Agent sessions can be interrupted after an operation has started but before the result reaches the transcript. The next Codex run should not blindly repeat every mutation. It should rediscover the service, inspect the latest deployment, and establish whether the previous operation reached a terminal state.

A Codex deployment runbook should classify commands as safe to repeat, safe only after inspection, or approval-gated. Reads are safe to repeat. Service creation requires discovery first. A new deploy is a new production event and should be recorded as such. Pruning and other destructive work remain human decisions.

Separate platform verification from application verification

Dockup can prove that a build completed, the container became ready, and minute-level probes observe the public service. Codex should still run application-specific checks: a public health endpoint, an authenticated test request, or a repository-provided smoke test that does not modify customer data.

The final result should state both layers. “Platform deployment succeeded” and “application smoke test passed” are different claims. When only the first is available, Codex should say so rather than compressing uncertainty into a green check mark.

Confirm the installed command surface before automation

A reusable Codex task should begin by checking dockup skill status --json and opening the current CLI reference when it depends on a less familiar option. This prevents a session from following an example written for another release.

The check is particularly useful in ephemeral runners where a fresh global npm installation may differ from a developer laptop. Codex can report the skill state before it performs the first production write, making the deployment record reproducible.

Final handoff

Keep the evidence.

Keep the target visible

Return the exact service target in the final report.

Preserve the source decision

Record whether Dockup used the repository Dockerfile or Nixpacks. This fact helps the next Codex session choose the correct build log and prevents a source-layout change from being mistaken for a platform incident.

Also record whether automatic deploy on push is enabled. A manual agent release and a push-triggered release can otherwise overlap and create two production events from the same investigation.

Put the workflow into production

Run the first Codex deployment against a disposable or low-risk service, then promote the same verified command contract to production.

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 Codex deploy a new Git repository with one command?

Yes. dockup create can create the service, deploy it, wait for the terminal result, and link the current directory when used with --deploy, --wait, and --link.

How should Codex authenticate to Dockup?

Use DOCKUP_TOKEN in the process environment and verify it with dockup whoami --json. This avoids interactive browser login in sandboxes and CI.

What proves that a Codex deployment succeeded?

The deploy command must exit 0 after running with --wait, and its JSON must report a successful terminal status. Follow with status, uptime, and application smoke checks.

Can Codex read production secrets from Dockup?

No. Secret values are masked in output. Codex can set or replace a secret but does not receive the stored value when listing configuration.

What should Codex do with needs_confirm?

It should stop and request explicit human approval. The error indicates that a destructive command was attempted without the required --yes confirmation.