Deploy from a Container Image
Instead of building your app from a git repository, you can point Vessl at a prebuilt container image in a registry and run it directly. There's no build step — Vessl pulls the image and runs it.
This is useful when you:
- Already build images in your own CI and just want Vessl to run them.
- Want to deploy an official or third-party image (e.g.
traefik/whoami,nginx, a vendor's app image). - Use a runtime or toolchain you'd rather not build on Vessl.
Everything else works exactly like a git-built app — environment variables, custom domains + SSL, health checks, scaling & replicas, persistent storage, rollbacks, and zero-downtime deploys all apply.
Deploy one
- New Application → give it a name and pick a target server.
- On the Source step, switch the toggle from Git repository to Container image.
- Enter an Image reference (see the format below).
- For a private registry, expand and fill the registry credentials (optional — public images need none).
- Continue through Add-ons, Build & Config (set the Target Port your image listens on, plus any env vars/resources), and Review, then Launch.
There's no build engine to choose for an image deploy — that section is replaced by a summary of the image you're running.
Image reference format
An image reference is [registry/]repository[:tag]:
| Example | Meaning |
|---|---|
traefik/whoami | Docker Hub, latest tag |
nginx:1.27-alpine | Docker Hub, pinned tag |
ghcr.io/acme/api:1.2.3 | GitHub Container Registry |
registry.example.com/team/app:sha-abc123 | Any OCI registry |
Prefer a specific, immutable tag (a version or commit SHA) over latest.
It makes deploys reproducible and rollbacks meaningful — latest can change
underneath you.
Private registries
For an image that isn't public, provide credentials on the Source step:
- Registry — the registry host (e.g.
ghcr.io). Leave blank for Docker Hub. - Username
- Password / token — an access token is recommended over a real password.
Vessl uses these only to authenticate the pull (a scoped docker login on the
target host, then docker logout afterwards). Credentials are encrypted at
rest, write-only (the API never returns the password — it shows ••••••••),
and never appear in logs or process listings. Username and password/token must be
provided together.
Reuse a saved credential
If you deploy several images from the same private registry, save the login once and reuse it. Go to Integrations → Registry Credentials and add a credential (name, registry host, username, password/token). Then, on the Source step's Registry access picker, choose that saved credential instead of re-typing it.
Saved credentials are scoped to your team, encrypted at rest, and can be reused across any of the team's image apps. A credential that's still in use by an app can't be deleted until you detach it.
Target Port & Start Command
- Target Port — set this to the port your image listens on (e.g.
80,3000,8080). Vessl routes the app's domain to this port. - Start Command — leave blank to run the image's own
CMD/ENTRYPOINT. Set it only if you need to override the default command.
Updating the image
To roll out a new build, push it to your registry and trigger a Deploy — Vessl re-pulls the image reference on each deploy, so a new push to the same tag (or a bumped tag) is picked up. To change the image reference itself or rotate registry credentials later, edit them in the app's Settings.
Security
Image containers run with the same isolation as every Vessl app — dropped raw network capability, no privilege escalation, and per-container CPU/RAM/PID limits. See the Security overview.
Notes & limits
- No build cache / build args. There's nothing to build, so build-specific options (build engine, build args, Dockerfile path) don't apply.
- Auto-deploy on git push doesn't apply to image apps (there's no repo). Push a new image and Deploy, or wire your CI to trigger a redeploy.
- The image must expose an HTTP service on the Target Port to be reachable through a domain — the same requirement as any web app.
See also: Build Engines · Dockerfile Builds · Databases & Add-ons.