Scalix Build

Build container images from a Git repo or an uploaded source tree. Runtime auto-detection, generated Dockerfiles, and per-build Firecracker isolation.

Overview

Scalix Build turns source code into a container image. Point it at a Git repo or upload a tarball; it detects the runtime, builds an OCI image, and pushes it to the Scalix Container Registry — ready to run on Scalix Run or Functions.

Every build runs in its own ephemeral Firecracker microVM with BuildKit, torn down when the build finishes. Nothing is shared between builds.

Base URL: https://api.scalix.world/v1/build

Scope: compute:deploy — the API key must be project-scoped

Quick Start

The fastest path is the CLI, which packages the current directory, builds it, and deploys the result as a service:

scalix-cloud deploy ./my-app

1/4 packaging source
2/4 uploading source (3.4 MB) and starting build
    build 8f2c1a90-...
3/4 building
4/4 deploying

Or drive the API directly:

curl -X POST https://api.scalix.world/v1/build \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "git",
    "source_url": "https://github.com/yourorg/api.git",
    "source_ref": "main",
    "image_tag": "api:1.4.0"
  }'

{
  "build": {
    "id": "8f2c1a90-...",
    "status": "pending",
    "source_type": "git",
    "source_ref": "main",
    "image_tag": "api:1.4.0",
    "timeout_seconds": 600,
    "created_at": "2026-08-02T09:14:22Z"
  }
}

Build from Git

POST /v1/build returns 201 Created.

Private repositories

Two options — pick one.

Install the Scalix GitHub App (recommended). Once installed for the project, builds mint a short-lived installation token per build automatically. Omit auth_token entirely.

# List repos the installation can reach
curl https://api.scalix.world/v1/integrations/github/repos \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Or pass a token — a fine-grained PAT with read-only Contents access on that one repository is enough:

curl -X POST https://api.scalix.world/v1/build \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "git",
    "source_url": "https://github.com/yourorg/private-api.git",
    "auth_token": "github_pat_..."
  }'

The token is held in memory for the build only. It is never stored, never written to build logs, and never echoed in error messages.

Build from an Upload

When the source isn't reachable from the internet, upload it instead. The request body is the gzipped tarball — metadata goes in the query string. Multipart is not accepted.

POST /v1/build/upload returns 201 Created.

tar czf - -C ./my-app . | curl -X POST \
  "https://api.scalix.world/v1/build/upload?image_tag=api:1.4.0&timeout_seconds=900" \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @-

Maximum upload: 256 MB gzipped. A body that is empty, not a gzipped tarball, oversized, or has malformed build_args returns 400.

Runtime Auto-Detection

With no Dockerfile in the tree, Build detects the runtime and generates one. Detection runs in this order — first match wins:

Node and Python versions come from the source when declared (engines.node, .nvmrc, python_requires); the table shows the fallback. index.html is checked last so a framework that also ships one keeps its real toolchain detection.

All generated images run as USER 1000, never root.

Static sites

If a build script is detected, the output directory is served by nginx. The toolchain-declared output dir is probed first, then dist, build, out, public, _site — first non-empty wins. A build that produces no output directory fails loudly rather than shipping an empty site. The nginx vhost listens on 8080 with an SPA history fallback, so client-side routes deep-link.

Build Args and Environment Variables

Project environment variables are merged into the build automatically, and the generated Dockerfile declares each key as ARG + ENV in the build stage — so NEXT_PUBLIC_* / VITE_* values exist when the bundler bakes them in.

build_args sent on the request win over project variables.

Build args are not secret. They are stored on the build record and readable back from GET /v1/build/{id}. Use them for a public API base URL, not a token. Runtime secrets belong in service environment variables.

Tracking a Build

Builds move through these states:

pending → fetching → detecting → building → completed
                                          ↘ failed
                                          ↘ cancelled

Terminal statuses are sticky — a cancelled build can never flip to completed.

Get a build

curl https://api.scalix.world/v1/build/$BUILD_ID \
  -H "Authorization: Bearer $SCALIX_API_KEY"

The record carries status, detected_runtime, image_ref, image_tag, build_args, error_message, timeout_seconds, and the started_at / completed_at / created_at timestamps.

List builds

curl https://api.scalix.world/v1/build \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Logs

curl https://api.scalix.world/v1/build/$BUILD_ID/logs \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Returns build_id, status, and logs.

Cancel

curl -X POST https://api.scalix.world/v1/build/$BUILD_ID/cancel \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Cancellation is real mid-build: the build VM is stopped, and a cancelled build bills nothing — the completion callback that triggers billing only fires on a genuine completion.

The Resulting Image

Images land in the Scalix Container Registry, keyed by project id. The project_id prefix is mandatory:

registry.scalix.world/<project-id>/<image-tag>

Pull it like any OCI image:

docker pull registry.scalix.world/8f2c1a90-.../api:1.4.0

Then run it. Scalix Run only accepts images from the Scalix registry, so build and push first:

curl -X POST https://api.scalix.world/v1/services \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api",
    "image": "registry.scalix.world/8f2c1a90-.../api:1.4.0",
    "port": 8080,
    "min_instances": 1
  }'

Build on Git Push

Connect a repo once, then every push builds — and optionally deploys.

curl -X POST https://api.scalix.world/v1/integrations \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "repo_url": "https://github.com/yourorg/api",
    "branch_filter": "main",
    "auto_build": true,
    "auto_deploy": true,
    "service_id": "svc_..."
  }'

The response returns the webhook_url and webhook_secret to register with your provider. With the Scalix GitHub App installed, the App's own webhook is accepted too — no manual webhook needed.

Manage integrations with GET, PUT, and DELETE on /v1/integrations/{id}.

Isolation and Limits

The builder service itself runs unprivileged with no build tooling installed — untrusted Dockerfiles never execute outside their microVM.

Agents (MCP)

Both require the compute:deploy scope. See MCP.

CLI

scalix-cloud deploy ./my-app          # package + build + deploy
 
scalix-cloud api build list-builds
scalix-cloud api build create-build --body '{"source_type":"git","source_url":"..."}'
scalix-cloud api build get-build $BUILD_ID
scalix-cloud api build get-build-logs $BUILD_ID
scalix-cloud api build cancel-build $BUILD_ID

scalix-cloud api build upload-build sends its --body as JSON, so it cannot carry a tarball. To upload source, use scalix-cloud deploy (which packages and posts the gzip stream for you) or the raw curl above.

Pricing

Rates verified against the live price book, 2026-08-02.

A build charges all four build meters: one build_starts, the rounded-up minutes, and the VM's vCPU and memory allocation × duration.

Failed and rejected builds are not metered. Cancelled builds bill nothing.

Included builds

The monthly allowance is counted in builds, not minutes.

Build minutes, vCPU-hours, GiB-hours, and registry storage carry no included allowance on any plan — they bill from the first unit. Registry pushes, pulls, and egress have their own per-plan allowances.

The Free plan has no build allowance. Builds draw against your starting credit balance, and because free accounts have overage disabled, the account becomes read-only once that balance is exhausted — Build and Registry stop accepting writes until you add credit or move to a paid plan.

Console

• Project → Builder — build history, live logs, cancel
• Project → Registry — images, tags, scan results
• Project → Settings → Integrations — connect repos, GitHub App install

Troubleshooting

See Also

• Build API reference — every endpoint, generated from the OpenAPI spec
• Scalix Run — deploying the built image
• Functions — serverless deployment
• Domains — pointing a domain at a service