Docs: How builds work | Maritime

How builds work

a build turns your repo or ZIP into the container image your agent runs. This page covers what happens between maritime deploy and a running agent. Applies to repo and ZIP deploys; template agents skip the build entirely (they are one image pull from live).

The pipeline

Repo and ZIP deploys build on a dedicated build machine, never on the host that runs your agent. BuildKit clones the repo at your chosen branch, builds the Dockerfile at the repo root, and ships the finished image to your agent's host through a private registry. A typical build plus ship lands in 1 to 3 minutes; if the builder was idle it cold-starts first, which adds about a minute.

The Dockerfile lives at the repo root, named exactly Dockerfile. There are no custom build args or targets; anything configurable belongs in env vars.
Layer cache carries over. Each build seeds from your agent's previous image, so rebuilds where dependencies did not change are fast. .dockerignore is honored for repo builds. ZIP uploads (500 MB compressed, 2 GB unpacked) skip it, so trim the archive yourself.
Private repos work. Install the Maritime GitHub App (Settings → GitHub) or connect GitHub OAuth. Build tokens are minted per build, never stored, and scrubbed from logs. Framework auto-detection cannot see private repos, so pass framework explicitly.
Pre-built images pull from any public registry (Docker Hub, GHCR, and friends). Private registries are not supported yet; build from a private repo instead.

Watching a build

The agent page streams the build log live under Overview → Builds. From the CLI:

maritime deploy my-brain --source github --repo https://github.com/acme/my-brain --wait

maritime history my-brain                                      # every attempt with its outcome
maritime history my-brain --json | jq -r '.[0].buildLog'       # full build log of the latest attempt

When builds fail

Builds fail loudly: the deployment is marked failed with the tail of the build output, and the agent stays in error until the next successful deploy. A build that prints nothing for 5 minutes is killed. Failed builds are not retried automatically (transient infrastructure errors are, up to three times); fix the Dockerfile and redeploy.