Startup Command Overrides

A startup command override changes how one app environment starts without changing or rebuilding its container image. This is useful when the same image can run more than one process, such as an API and a worker:

Image default: bun run start:api
Worker environment override: bun run start:worker

The override belongs to the app environment, not to the app or build. The same source build or pre-built image can therefore run with different startup commands in different environments.

Configure it in the dashboard

Open the app environment, expand the collapsed Advanced settings section, and find Startup command:

1. Enter a complete command line, or leave Command empty to preserve the image entrypoint.
2. Optionally add one exact argument per line.
3. Optionally set a working directory inside the container.
4. Keep Run through shell enabled for a command line such as bun run start:worker. Disable it for an exact executable plus arguments.
5. Select Save startup command.
6. Apply the pending deploy change, or include it in the next deployment.

Use Reset to image defaults to remove the complete override. The next deployment will use the image ENTRYPOINT, CMD, and working directory again.

Configuration fields

Field	Description
command	Complete shell command when shell is true, or one exact executable when shell is false.
args	Exact argument array. With no saved command, an args-only override preserves the image ENTRYPOINT and replaces its default CMD.
shell	Runs command through /bin/sh -lc when true. The default for a new command is true.
workingDir	Working directory inside the container. It can be set without a command or arguments.

Shell mode requires the image to contain /bin/sh. Use direct mode for distroless images or when exact argument boundaries matter.

command accepts up to 16,384 characters. args accepts up to 128 values of 4,096 characters each, including an empty-string argument. workingDir accepts up to 4,096 characters. A complete override must include command, at least one argument, or workingDir, and shell requires command. A partial API or MCP update can send shell by itself to change the mode of a saved command, or args: [] to remove saved arguments. The final merged override must still be valid.

In the dashboard Arguments editor, an empty editor means no argument override. Enter "" on its own line to preserve one empty-string argument. Quoted lines use JSON string notation, which also makes embedded newlines and literal quote characters re-enterable without changing argument boundaries.

CLI examples

Complete shell command

This is the simplest form for most images. --command defaults to shell mode:

quaveone deploy \
  --env acme-worker-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --command "bun run start:worker" \
  --wait

Exact executable and arguments

Use --shell=false and repeat --arg to preserve argument boundaries:

quaveone deploy \
  --env acme-worker-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --command bun \
  --shell=false \
  --arg run \
  --arg start:worker \
  --wait

Preserve the image entrypoint

On an environment without a saved command, omit --command and pass only arguments. This preserves the image ENTRYPOINT and replaces its default arguments:

quaveone deploy \
  --env acme-worker-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --replace-startup-config \
  --arg run \
  --arg start:worker

Startup updates are partial by default. If the environment already has a saved command, an args-only update preserves that command. The --replace-startup-config flag makes the supplied startup flags the complete desired override, so this example removes any saved command, shell mode, and working directory while keeping only the arguments.

Working directory only

On an environment without a saved command or arguments, pass only --working-dir to keep both image command defaults:

quaveone deploy \
  --env acme-api-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --working-dir /srv/app

On an environment that already has a startup override, this partial update preserves its saved command and arguments.

Restore image defaults

--clear-command clears the command, arguments, shell mode, and working directory together. It cannot be combined with the startup override flags.

quaveone deploy \
  --env acme-worker-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --clear-command \
  --wait

Source builds and image deploys

Startup configuration works the same way for source uploads and pre-built images:

# Build the source, then start the resulting image as a worker
quaveone deploy \
  --env acme-worker-production \
  --dir . \
  --command "bun run start:worker"

# Skip the build and start an existing image as a worker
quaveone deploy \
  --env acme-worker-production \
  --image ghcr.io/acme/platform:2026-07-13 \
  --command "bun run start:worker"

The startup override is runtime configuration. It is not included in the build configuration or image-reuse hash, so changing only the startup command does not make the source or image different. A source deployment still follows the normal build flow, and Quave ONE can reuse an equivalent existing image.

The saved startup configuration remains associated with the environment across new image versions, redeploys, and rollbacks. It is also included in deployment configuration history so pending and applied deploy settings stay visible.

Partial updates and clearing

CLI, Public API, and MCP startup updates preserve saved fields that are omitted by default. For example, updating only workingDir keeps the saved command and arguments.

For CLI deployments, add --replace-startup-config when the startup flags are the complete desired override. Public API image deploy, source upload, build, and environment-update requests, plus the equivalent MCP deployment tools, can send replaceStartupConfig: true with startupConfig for the same exact replacement. The flag requires a complete startupConfig and cannot be combined with clearStartupConfig.

Use clearStartupConfig: true through the Public API or MCP to clear the whole override. Do not send startupConfig and clearStartupConfig in the same request.

Supported workloads

Startup overrides are supported for regular Apps and Functions. They are not supported for Jobs or Databases & Services:

• Jobs already have per-environment and per-run command configuration. See Jobs.
• Databases & Services use commands managed by Quave ONE.

A long-running worker can use a regular App environment. If it does not serve HTTP, disable HTTP probes that expect a web endpoint. See HTTP Probes.

Security

Do not put passwords, tokens, or other secrets in commands or arguments. Store them as secret runtime environment variables instead. Quave ONE records only a summary of startup configuration changes in audit events and redacts raw startup command payloads from MCP request logs.

See also:

• CLI
• Deploy with Image
• Functions
• App Environments API
• App Environment Deployments API
• Code API
• MCP