Build Args & Custom Build Command
Vessl gives you two ways to customize how your app is built: build args for passing values into a Dockerfile at build time, and a custom build command for overriding what Nixpacks or Docker runs during the build step.
Both are configured during app creation (in the Source step) or later via Settings → Build.
Build args (Dockerfile builds)
Build args are ARG values passed to your Dockerfile via --build-arg. They're useful for things like specifying a Node version, passing a NEXT_PUBLIC_* variable that needs to be baked into a static build, or any value your Dockerfile references with ARG.
In the wizard or settings, enter build args one per line in KEY=VALUE format:
NODE_VERSION=20
NEXT_PUBLIC_API_URL=https://api.example.com
SENTRY_DSN=https://[email protected]/123
In your Dockerfile, reference them with ARG:
ARG NODE_VERSION=18
FROM node:${NODE_VERSION}-alpine
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
Build args are baked into the Docker image layers and can be inspected. Don't use them for runtime secrets like API keys or database passwords — use the Variables tab for those instead.
Custom build command
The build command field lets you override the default build step that Nixpacks or Docker runs.
For Nixpacks builds, you can pass extra flags to the nixpacks build invocation. For example, to force a specific provider or pass additional build options:
--build-cmd "npm run build:prod"
For Dockerfile builds, the build command field passes extra flags to docker build. For example, to set a build target:
--target production
Leave this field empty to use Vessl's defaults — Nixpacks auto-detects your stack and runs the appropriate build, while Dockerfile builds use docker build with no extra flags.
Root Directory (monorepos)
If your repository contains multiple apps and you want to deploy a specific subdirectory, set the Root Directory field to the path of that subfolder (e.g. backend or apps/api).
Vessl resolves all paths — including the Dockerfile location and Nixpacks detection — relative to this root directory. The rest of the repository outside that folder is ignored during the build.
See Monorepos & Root Directory for a full walkthrough.