Deploy from source (Dockerfile)

A source deploy turns a directory on your machine into a running serverless service in one step: you upload the directory, the platform builds its Dockerfile on its own build service, pushes the image to a repository in your own Crusoe Cloud Registry, and rolls it out as a service. You never run Docker locally and you never push an image yourself.

Your project needs a Crusoe Cloud connection first

Because the built image goes into your own Crusoe Cloud Registry, a project with no Crusoe Cloud credential is refused at submit — nothing is built. A project admin connects it once with platformctl crusoe-cloud connect, or Project Settings in the console; a project that is already connected needs nothing new. See connect your Crusoe Cloud account.

This applies only to source deploys. Deploying an image you already published builds nothing, so it does not need the connection — though pulling a private image from your own registry still does.

Use it when the image-based deploy is friction — you have code and a Dockerfile, not a published image. Everything about the running service is identical: same scale-to-zero, same publishing, same triggers, same quota.

The container contract

Your Dockerfile is built exactly as written — your base image, your build steps. The running container has three rules:

1. Listen on $PORT. The platform sends traffic to the port named in the PORT environment variable (8080 in practice). Hard-coding 8080 also works today; reading $PORT is the portable form.
2. Run as a non-root user. The platform starts the container as uid 65532 regardless of what the image says. Most -slim and distroless base images work as an arbitrary uid out of the box; an image that must write to / as root will crash-loop.
3. No platform credentials are injected. A source-deployed container gets a deliberately minimal environment — your own environment variables and secrets, the PORT contract, and the crusoe.secret() consumer credentials — and none of the agent/function harness wiring (no memory-store or vector-database addresses or credentials). It is your image and your contract; talk to platform services through their public APIs with credentials you choose to give it.

Deploy

Your directory must have a Dockerfile at its root.

platformctl

platformctl serverless deploy ./my-service --name my-service

The CLI refuses the upload if there is no Dockerfile at the root, before anything is packed. The command streams the build and waits until the service is ready or the build fails — the builder's own output is shown on failure.

Try it with the shipped example:

platformctl serverless deploy examples/serverless/hello-container --name hello-container

examples/serverless/hello-container is a two-file directory — a Dockerfile and a stdlib-only server.py that answers JSON on $PORT — and is the smallest template worth copying.

curl

A source deploy goes through the same build path as agents and functions, so it is POST /v1/agents with framework=container and a .tar.gz whose root holds the Dockerfile:

tar -czf my-service.tar.gz -C my-service .
curl -s -X POST "$CAI_API/v1/agents" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -F "name=my-service" \
  -F "framework=container" \
  -F "code=@my-service.tar.gz"

You should see (HTTP 202 — the build runs in the background):

{"agent": "my-service", "build_id": "2f6f2f6e-8a1e-4c3b-9d2a-1b2c3d4e5f6a"}

Without a Dockerfile at the archive root, the request is rejected outright rather than failing later in the build.

Note the endpoint: this is $CAI_API, the platform API that owns builds — not $CAI_SERVERLESS_API, which deploys images that already exist. Poll GET /v1/agents/my-service until its ready is true; the state beside it walks building → deploying → ready, and carries failed with a message if the build does not survive.

Console

On the project's Serverless page, choose Deploy from source. The dialog opens a code editor seeded with a starter Dockerfile — write your source in tabs, upload files, or upload a ready-made .tar.gz. The build progress (and, on failure, the builder's own output) stays on screen; when the build settles ready you land on the new service's page.

After the deploy

The result is an ordinary serverless service plus a stored copy of your source:

• It appears on the Serverless page and in platformctl serverless list, and everything on the service detail page works — edit env, publish, split traffic, attach triggers.
• Because the build went through the same path agents and functions use, the source is stored: fetch it as a zip with platformctl agents files download <name>, or read and edit individual files with platformctl agents files get|put.
• Redeploying the same name replaces the source and rolls out a new revision built from the new Dockerfile — from the CLI, or by running Deploy from source again with the same name in the console.

Limits and failure modes

• Upload size is capped the same as agent/function deploys (the whole directory, compressed).
• Build time is bounded by the platform's build timeout; a build that exceeds it fails with the builder output kept.
• No build args or secrets at build time. The build gets your files and nothing else — do not bake credentials into the image; set them as env/secrets on the service instead.
• A container that never listens on $PORT deploys an image successfully and then fails its rollout — the service page shows the revision's error. See troubleshooting.