Update a Remote Docker Container Image Without SSH — Stacker CLI

What You'll Do

Push a new Docker image tag to a running app on a remote server — from your laptop, in one command, without SSH-ing in. No docker pull, no editing compose on the box, no server login. The Stacker CLI talks to the Status Panel agent already running on your deployment, so you preview the change, apply it, and confirm the new image is live, all from your terminal.

Update a container's image with a single command
Preview the change first with a read-only plan
Verify the new image is running
Keep stacker.yml in sync so the change sticks

Quick Answer

stacker agent deploy-app <app-code> --image <image>:<tag> --force

Example: stacker agent deploy-app app --image myorg/api:v2.1 --force. Done — the running container is recreated on the new image, no SSH required.

Why No SSH?

When you deploy with Stacker (with monitoring.status_panel: true), a small Status Panel agent runs alongside your containers. The CLI sends it commands over the message bus — so updating an image is an API call, not a shell session. You don't open a terminal on the server, you don't run docker by hand, and there's an audit trail of what changed.

Step 1: Find the App Code

Every container is addressed by its app code. List them:

stacker agent apps
# or, with live health/images:
stacker agent health
# CONTAINER        STATE      IMAGE
# project-app-1    running    myorg/api:v2.0

The app code is the service name (e.g. app, or a named service).

Step 2: Preview the Change (Recommended)

Before touching production, ask for a read-only plan. It shows exactly what will change and returns a fingerprint you apply verbatim — so what you reviewed is exactly what runs:

stacker agent deploy-app app --image myorg/api:v2.1 --plan

Review the plan, then apply it by fingerprint:

stacker agent deploy-app app --apply-plan <fingerprint>

Step 3: Or Just Apply It

If you don't need the preview, update in one shot:

stacker agent deploy-app app --image myorg/api:v2.1 --force

--image is the full reference including the tag (myorg/api:v2.1, nginx:1.27, caronc/apprise:latest). There's no separate --tag flag — the tag is part of the image.
--force recreates the container so it actually pulls and restarts on the new image.

Step 4: Verify It's Live

Confirm the new image is the one running — the IMAGE column is the proof:

stacker agent health
# project-app-1    running    myorg/api:v2.1     ← new tag, up

stacker agent logs app --limit 100    # sanity-check startup

Useful Flags

Flag	What it does
`--deployment <hash>`	Target a specific deployment (otherwise the active agent for the project is used)
`--env <name>`	Select an environment/profile (`local` / `dev` / `prod`)
`--runtime kata\|runc`	Container runtime (default `runc`)
`--json`	Machine-readable output for scripts/CI

Keep `stacker.yml` in Sync

agent deploy-app updates the running container on the server directly — it does not rewrite your local stacker.yml. That's perfect for a hotfix or a quick roll-forward, but it means a future full deploy (stacker deploy) would use whatever image is still pinned in your config. So after the update, bump the tag in stacker.yml too:

app:
  type: custom
  image: myorg/api:v2.1     # was v2.0

Now the new image is both live and the persistent default — no surprise rollback on the next full deploy.

Roll Back the Same Way

Rolling back is just deploying the previous tag — again, no SSH:

stacker agent deploy-app app --image myorg/api:v2.0 --force

Frequently Asked Questions

Do I need SSH access at all?

No. The command goes through the Status Panel agent over the message bus. (Stacker still keeps an emergency SSH key for you — see stacker status — but you don't need it for image updates.)

Does this pull the image automatically?

Yes — with --force the agent recreates the container, which pulls the specified image if it isn't already present.

What about private registries?

Configure registry credentials for the deployment (via deploy.registry or the STACKER_DOCKER_* env vars) so the agent can pull private images.

Can I update several apps at once?

Run one agent deploy-app per app code. Scripting it with --json makes multi-app roll-outs a short shell loop.

How do I know it worked?

stacker agent health shows the live IMAGE per container — if it reads your new tag and the container is running, you're done. Pair it with stacker monitor to be alerted if the new image crashloops.

Key Takeaways

stacker agent deploy-app <app> --image <image>:<tag> --force updates a running container's image — no SSH
--plan → --apply-plan <fingerprint> lets you review before applying to production
stacker agent health confirms the new image is live (the IMAGE column)
Also bump the tag in stacker.yml so a future full deploy doesn't revert it
Rollback is the same command with the previous tag