[Bug]: official Dockerfile ships no agent CLI — opencode/Vela login required workaround

Author: estebanmunchjones2019Created Sep 17, 2026Updated Sep 17, 2026
Labelsbuggood first issuehelp wanted

Description

The official deploy/Dockerfile (runtime stage, node:24-alpine) ships no agent CLI at all — neither OpenCode nor the Vela CLI is installed in the image. On a fresh container built from this Dockerfile, any start_run against the opencode/byok-opencode agent fails immediately:

start opencode server: opencode binary not found; install a Vela CLI release
package with bundled OpenCode or set VELA_OPENCODE_BIN for development/debugging:
exec: "opencode": executable file not found in $PATH

and agent: "amr" fails with:

Agent "AMR" (`vela`) is not installed or not on PATH. Install it and refresh
the agent list (GET /api/agents) before retrying.

Deployments that intentionally do not want to depend on Vela Cloud login (headless/self-hosted setups, or any autonomous agent that can't complete an interactive browser-based login flow) have no supported first-party path to a working local agent runtime — the only documented recovery (VELA_OPENCODE_BIN pointing at a Vela-resource-provided binary) itself requires a Vela login to populate that path.

Steps to reproduce

  1. Build the image from the official deploy/Dockerfile on main.
  2. Start the container and call start_run with agent: "opencode".
  3. Observe the opencode binary not found failure above — the runtime image has no opencode/opencode-ai package installed.

Working fix (verified)

Install the opencode-ai npm package directly in the runtime stage and set VELA_OPENCODE_BIN to its resolved binary path, without touching Vela at all:

ARG BASE_IMAGE=ghcr.io/nexu-io/od:latest
ARG OPENCODE_VERSION=1.18.30
FROM ${BASE_IMAGE}

USER root
RUN npm install --global --omit=dev "opencode-ai@${OPENCODE_VERSION}" \
    && test -x /usr/local/bin/opencode \
    && /usr/local/bin/opencode --version
ENV VELA_OPENCODE_BIN=/usr/local/bin/opencode

Verified end-to-end after this change:

  • GET /api/agents reports opencode and byok-opencode as available: true with a real version string (1.18.30).
  • start_run with agent: "opencode" reaches status: "succeeded" with a real artifact.
  • A separate custom-image/Jarvis media-generation task (surface: "image") also completed and produced a real, verified 1024×1024 JPEG — confirming the daemon and its media pipeline work fully without any Vela authentication.
  • agent: "amr" correctly stays AGENT_UNAVAILABLE (no vela binary) — expected and desired for this deployment, since installing the Vela CLI would reintroduce the login dependency being avoided.

Proposed fix

Either:

  • Add an optional build arg/stage to deploy/Dockerfile that installs opencode-ai at a pinned version (mirroring the pattern above), so self-hosted/headless deployments get a working local-agent runtime out of the box without needing Vela Cloud login, or
  • At minimum, document this exact workaround in the deployment docs (the current guidance only points at Vela CLI installation, which reintroduces the login requirement these deployments are trying to avoid).

Environment

  • Open Design daemon (self-built from deploy/Dockerfile, main branch)
  • Deployment: Docker Compose, Linux x86_64
  • opencode-ai version tested: 1.18.30