Delivery format

Submit a ZIP or a GitHub snapshot (repo + branch/tag via the Velcio GitHub App). Same layout rules and 25 MB limit either way.

GitHub import is a one-time snapshot of the ref at submit. Not continuous deploy. Connect the App under Developer profile before private repos. After accept, the buyer downloads a ZIP from Velcio. They do not get clone access to your repo. Connect and submit: Developer workflow.

At submit, pick process mode (required, no default):

• Worker: long-running process, no public URL
• Web: HTTP on https://{slug}.velcio.app. Use Web for inbound webhooks or any public HTTP. See Web delivery format for PORT

Worker vs Web examples: Choosing Worker or Web.

Build modes

When Firecracker build helpers are on the worker:

Mode	When to use	What you provide
Auto (buildpacks)	Default for new deliveries	Source tree. Optional build command and start command
Dockerfile	Escape hatch (Go, Rust, C, custom images)	Exactly one Dockerfile (or Dockerfile.<name>). Optional start override

Go and Rust usually Auto or Dockerfile. C usually needs a Dockerfile (or explicit build/start commands).

Not supported

Worker and Web apps only. Not CMS appliances.

• WordPress / classic PHP CMS: not supported. No WordPress ZIPs, wordpress: bases or Dockerfiles whose job is to run WordPress
• .NET: not first-class. Official Microsoft images (mcr.microsoft.com/dotnet/…) are outside the Dockerfile allowlist
• Multi-service Compose: optional when MULTI_SERVICE_COMPOSE_ENABLED is on. Root compose.yml with two or more services. Each service needs a Dockerfile in its build: context. Each service gets its own URL and counts as a separate hosting app. Open app uses the entrypoint. Other web services show as secondary links. Stateful images (Postgres, MySQL, Redis, MongoDB and similar) are always rejected. Single apps still use Auto or one Dockerfile without Compose.

Auto (buildpacks)

Ship language-native source. Velcio runs Cloud Native Buildpacks (pack) with a pinned builder inside a Firecracker build microVM.

• Build command: extra compile/asset step when needed
• Start command: process override (or a Procfile)

Web apps still bind $PORT and implement GET /healthz.

Dockerfile mode

Exactly one Dockerfile in the archive. Validated against an allowlist and built in the Firecracker guest (not on the host Docker daemon for untrusted Dockerfiles). Optional start command appends a CMD override.

Every FROM and COPY --from= image must start with one of:

• python:
• node:
• golang:
• rust:
• eclipse-temurin: (Java)
• debian:
• ubuntu:
• alpine:
• gcr.io/distroless/
• paketobuildpacks/

Anything else is rejected (for example mcr.microsoft.com/dotnet/…, arbitrary ghcr.io/…, wordpress:).

Web apps: PORT and health

For Web, Velcio sets PORT=8080 and proxies public HTTPS only there. Listen on 0.0.0.0 with env PORT. Implement GET /healthz with HTTP 2xx. Wrong port → 502. Missing route → 404 on /healthz. Full detail: Web delivery format.

Scratch disk (/tmp and /data)

Read-only root. Write to /tmp (64 MB) and /data via VELCIO_DATA_DIR=/data (~25% of plan RAM). Ephemeral. Wiped on redeploy. Details: Web delivery format.

Common rules (all modes)

• No unsafe archive paths (.. or absolute)
• Dependencies install in Velcio's build. Keep archives lean
• Never put secret values in the ZIP. Declare env var names in Velcio. The buyer sets values. Build excludes .env* (including .env.example)
• Rights transfer on accept. When the buyer accepts your delivery or a revision, they own that submitted code. Do not reuse it for other clients unless they agree outside Velcio

Required environment variables

1. Open Required environment variables on the project while in_progress
2. Add keys your app reads. Database apps often use DATABASE_URL (quick-add if offered)
3. Save early so the buyer can fill values before you submit
4. Confirm the same list at submit (ZIP or GitHub)

Deploy is blocked until every required key has a buyer value.

Failed builds and verification

Validation or build failure → status failed, project back to in_progress. Submit a fix or Retry deploy / Rebuild.

After a good deploy, status stays submitted while you verify. Buyer review starts only when you confirm delivery.