Your First Deployment

Use vxl up when you want an app plus databases or Redis from avoxeltron.yaml file. Use vxl deploy to deploy a single image, git repository or local directory.

If you have not connected a server yet, follow the quickstartfirst. Every command below uses the prod server profile.

Deploy from a manifest

A manifest is the normal path, from your app's own source or from an image. In the directory that holds your app and its Dockerfile, scaffold one withvxl init, or write it yourself. This example builds the current directory and adds a Postgres database:

name: hello

app:
  build: .
  port: 8080
  health: /healthz
  domain: hello.example.com

services:
  db:
    type: postgres
    disk: 1GB

The daemon builds the directory for vxl up. To run a prebuilt image instead, replace build: . with image: and a reference the daemon can pull, or one already in its local Docker image store.

Preview the translated request, then deploy:

$ vxl up --dry-run
$ vxl up --server prod --yes

--dry-run prints the DeployProductRequest as JSON without contacting the daemon. Check that it contains a product key, an app component with an image, and a Postgres component.

Manifest fields

FieldMeaning
nameProduct key. Required and non-empty.
app.buildDirectory to build, relative to the manifest. Use this or app.image.
app.imageImage reference for the app.
app.portPort the app listens on inside its container.
app.healthHTTP health path. Defaults to /.
app.domainHostname routed through Caddy.
app.runtimeauto or docker.
app.writable_pathsExtra tmpfs mounts on the read-only root, for example /var/cache/app or /srv/uploads:size=256m. Defaults to 64 MiB each.
services.<name>.typepostgres or redis.
services.<name>.diskVolume size, for example 1GB.

The manifest has exactly one app, and unknown keys are rejected rather than ignored.

App containers run with a read-only root filesystem. Only /run (16 MiB),/tmp and /var/tmp (64 MiB each) are writable, asnoexec,nosuid,nodev tmpfs. If the image writes elsewhere, list the path underapp.writable_paths. See the manifest reference for the limits.
A postgres service injects DATABASE_URL; a redisservice injects REDIS_URL. Setting that variable yourself is an error.
Every Linux capability is dropped. For nginx, usenginxinc/nginx-unprivileged and listen on port 8080. The stocknginx image's entrypoint needs CHOWN, SETUID andSETGID, so it exits at once and the deploy says the image needs root capabilities.

Deploy a single app without a manifest

Deploy a public image:

$ vxl deploy nginxinc/nginx-unprivileged:1.27-alpine --name web --server prod --domain web.example.com --internal-port 8080 --wait

Deploy a git repository:

$ vxl deploy https://github.com/you/app.git \
    --name app \
    --server prod \
    --git-commit <40-hex commit sha> \
    --wait

Git sources must be pinned. Pass --git-commit with a full commit sha, or--git-tag, which is resolved to its commit when the build fetches it. A branch alone is refused because it moves.

--type forces auto, image, git orpath. --build-engine selects dockerfile,railpack or nixpacks. --wait blocks until the deployment is healthy and exits non-zero if it does not become healthy.

Build a server directory with vxl deploy

vxl deploy . asks the daemon to read a directory on the server itself, so it is refused by default. An operator admin may use it, or the server's config must allow the directory, which the voxeltron service user must be able to read:

[security]
allowed_local_path_roots = ["/srv/apps"]
$ cd /srv/apps/api
$ vxl deploy . --name api --server prod --wait

For your own source, vxl up with build: . needs neither.

Domains and the edge

--domain routes through the local Caddy edge by default. Caddy obtains the certificate, so set proxy.acme.email first. To route through Cloudflare Tunnel instead, ask for it explicitly:

$ vxl deploy ghcr.io/you/api:1 --name api --server prod --domain api.example.com --edge cloudflare

The Cloudflare path requires a configured token and zone. vxl deploy reports public routing only when it was actually enabled; use--allow-private-domain-fallback only when you accept a recorded domain with no verified public route.

Environment and secrets

Pass non-secret values with repeatable flags:

$ vxl deploy ghcr.io/you/api:1 --name api --server prod --env NODE_ENV=production --wait

Store secrets in the daemon, then reference them in the manifest or deployment environment:

$ vxl secrets set --server prod --project=api STRIPE_KEY -
# reads the value from stdin
$ vxl secrets list --server prod --project=api

vxl secrets get, vxl secrets delete andvxl secrets copy manage existing values. A value passed with- is read from stdin so it does not land in shell history.

Check a deployment

$ vxl app list --server prod
$ vxl app status --name api --server prod
$ vxl deploy status --name api --server prod
$ vxl deploy logs --deployment-id <deployment-id> --server prod

vxl deploy logs follows the stream by default. Use --tailand --since to narrow it.

For scripts, request structured output:

$ vxl status api --server prod --json

Roll back

In the TUI, open the projects or deployments section and press r on the deployment to roll back. The daemon keeps the previous deployment available while the replacement is brought up.

From the command line, roll back by deployment id:

$ vxl deploy rollback <deployment-id> --server prod

To select an older deployment by id for an app, use the top-level command:

$ vxl rollback api --to <deployment-id> --server prod --yes

Omit --to to restore the previous deployment.

Restart an app

Restart with the saved configuration. Select one component, or omit the flag to restart all components:

$ vxl restart api --component web --server prod --yes

Without --yes, rollback and restart ask for confirmation in a terminal. Use --yes in automation.

Remove a manifest product

$ vxl down --file voxeltron.yaml --server prod --yes

vxl down removes the components owned by that product. Local state is deleted only after the daemon confirms the removal.