Documentation Run your app

Container compatibility

Which image, Compose and listener features a container deployment supports.

~25 min read
On this page

Gregale's container contract is:

A stateless Linux/amd64 OCI image that starts an HTTP server on 0.0.0.0:$PORT can be deployed without rewriting it as a function.

Deploy an existing image directly:

sh
gregale doctor --image registry.example.com/team/api@sha256:<digest>
gregale deploy --image registry.example.com/team/api@sha256:<digest>

Gregale preserves the OCI/Docker process model. Image metadata supplies the entrypoint, command, environment, working directory, user, health check, stop signal, and exposed ports. Deployment overrides can replace the start command, port, or readiness settings. An explicit port wins; otherwise a single exposed TCP port seeds the default.

This makes existing Go, Rust, Java, Spring, .NET, Node, Python, nginx, custom binaries, and Docker applications portable. Images can come from a Dockerfile or an OCI registry. A multi-platform index resolves to its Linux/amd64 image.

Images that do not share a Gregale-optimized base can use a self-contained full-rootfs deployment. Paid plans enable that path automatically; Free plans currently require an explicit opt-in. The resulting workload still uses the same Firecracker isolation, snapshots, metering, routing, and scale-to-zero lifecycle.

The portability boundary is intentionally small: Linux/amd64, a stateless HTTP listener reachable on 0.0.0.0, and a process that honors PORT (default 8080). The root filesystem is ephemeral. OCI volumes and host mounts do not create durable storage, and privileged mode, host devices, host networking, and the Docker socket are not supported.

Persistent container disks are outside Gregale's service contract. Store durable application state in object storage or an external database. Snapshot reuse is a startup optimization and does not guarantee filesystem persistence across instances, cold fallback, redeployment, or node failure. The ephemeral disk allowance includes application content and filesystem overhead, rather than guaranteeing that amount of free scratch space.

While an image is assembled, its layers may write at most twice the plan's ephemeral disk allowance in file content (LayerExtractionBudgetMultiple). Content that a later layer replaces or deletes still counts toward this budget. The layers may also apply at most 2,000,000 entries in total (files, directories, links and whiteouts, LayerExtractionMaxEntries), twice the 1,000,000 entries the runtime scan accepts. An image that exceeds either limit fails with app_layer_too_large before assembly finishes. A registry blob download may wait up to 60 seconds for headers or for its next bytes, and may take up to 30 minutes in total.

Direct OCI images use TCP listener readiness by default; Gregale does not invent a /healthz endpoint that the image never declared. An explicit deployment health-path override selects HTTP readiness instead.

For an image with TCP readiness and no HTTP health path, the post-readiness public smoke checks candidate route connectivity at /. A candidate-authored 2xx, 3xx, 401, 403, or 404 response can verify connectivity; an API does not need to implement a successful root route. Gateway errors, missing candidate response evidence, a different revision, 429, and 5xx still fail verification. An explicit HTTP health path (including /) continues to require 2xx.

The deployment's hosting_receipt.smoke.verification records http_health or route_connectivity, alongside the actual response status. authentication: platform_challenge means the platform probe bypassed Gregale customer access gates; it does not prove anonymous access or bypass application-owned authentication. Connectivity probes record redirects without following them.

Both candidate verification contracts require an authenticated candidate response, including explicit HTTP health checks. A deployment header alone, gateway error, or missing/invalid response proof cannot verify the candidate. Candidate redirects are never followed; HTTP health requires a proven 2xx on the configured path.

If challenge publication, the public gateway response, or the verification transport remains unavailable, the candidate stays snapshotting and retries through the durable notification outbox. A transport failure does not establish whether the app or platform caused it. The existing serving deployment keeps traffic. Recovery progress is available in stage_state.hosting_verification: attempts, deadline_at, last_error_code, and retry_not_before (the earliest eligible retry, not a promised delivery time). last_error_code distinguishes publication, gateway, transport, missing-proof and wrong-deployment failures. The five-minute recovery window survives platform restarts and changes of outage reason. If it expires, the deployment fails with deployment_verification_unavailable; inspect deployment and gateway diagnostics before retrying. A proven candidate response with an unhealthy status retains deployment_smoke_failed.

Roll out response-proof support to all gateways before enabling this verifier for HTTP health checks; an older gateway cannot verify a candidate.

Gregale adds the managed infrastructure around that process: TLS, readiness, logs and metrics, snapshots, autoscaling, and scale-to-zero.

Runtime environment

The process starts in the environment a container runtime provides:

GregaleDocker
HOMEThe image or deployment value; else the user's passwd home when the user can write there; else /tmpThe image value, else the passwd home
PATHThe image or deployment value, else /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/binSame
Working directoryWORKDIR, created for the process user when missingSame
Open files (ulimit -n)65,536 soft, 1,048,576 hardVaries by host; Kubernetes gives 1,048,576
HostnamegregaleThe container ID
/etc/hostsThe image's file, plus 127.0.0.1 localhost and 10.0.0.2 <hostname> when it lacks themGenerated; image entries ignored
/tmpRAM-backed tmpfs, up to half the instance's RAM, starting with the image's /tmp filesThe image's directory on the container disk
/dev/shmtmpfs, up to half the instance's RAM64 MB tmpfs
/dev/ptsMountedMounted

Files in /tmp and /dev/shm use the instance's memory: filling them hits the plan's RAM limit, not a disk-full error. Write large scratch files under the home directory or the working directory instead; that space counts against the ephemeral disk allowance.

Randomness after a snapshot restore

A scaled-to-zero app wakes from a snapshot of its running process, so any random generator the process held in memory is restored with it. The guest kernel is reseeded on every wake, so anything that reads the kernel on each call is always safe: /dev/urandom, getrandom(2), Go crypto/rand, Python secrets, os.urandom and uuid.uuid4, and Node crypto.webcrypto.

For Node and Python, Gregale also reseeds the process itself before a woken instance serves traffic. It covers Node crypto (and the OpenSSL state behind TLS), crypto.randomUUID, crypto.randomInt and Math.random, and Python random, ssl, and numpy's global numpy.random functions. If a process cannot confirm the reseed, the instance cold-boots instead of waking from the snapshot.

Java on Java 16 or newer is reseeded the same way: Gregale adds a small agent to JAVA_TOOL_OPTIONS, which resets Math.random, ThreadLocalRandom, SplittableRandom and the seed that a new Random() draws from. Every JVM then prints Picked up JAVA_TOOL_OPTIONS: … on stderr when it starts. Java's default SecureRandom reads the kernel and needs nothing.

A JVM built with jlink cannot load any agent unless it includes the java.instrument module, and it would not start with one named. When the image holds such a JVM, Gregale leaves the agent out, so the app starts but its JVMs are not reseeded and Gregale warns on each wake. Add --add-modules java.instrument to the jlink command to keep the reseed.

Go cannot be reseeded from outside the program. Use crypto/rand for anything that must be unique. To reseed generators your program owns, import github.com/gregale-dev/gregale-go/reseed and register a callback with reseed.OnRestore; Gregale runs it after each restore, before the instance serves traffic.

Reseed these yourself, or avoid keeping them across a snapshot:

  • Go math/rand and math/rand/v2 global functions, Ruby Random, and PHP mt_rand. Two restores of one snapshot return the same Go values (measured);
  • a Java Random object, or a SecureRandom you seed yourself or create as SHA1PRNG, that your code created before the snapshot, and any JVM older than Java 16;
  • generator objects your code created before the snapshot, such as Python random.Random() or numpy.random.default_rng();
  • values your code generated before the snapshot, such as a secret, nonce or instance ID drawn once at startup: every instance restored from that snapshot holds the same value. Draw them per request or per use, and take the serving instance from the X-Faas-Instance-Id request header or, outside a request, from the file named by FAAS_INSTANCE_IDENTITY_FILE, which Gregale rewrites on every wake (trace propagation);
  • Math.random inside Node worker threads;
  • sidecars that run from their own root filesystem;
  • Bun and Deno, which do not load the Node reseed; Python started with -S, -E or -I, which skips the Python reseed; and any Node, Python or Java process started with a cleared environment. Gregale logs a warning on each wake when it finds such a process running, or a Go program that does not import the reseed package;
  • OpenSSL copies bundled inside Python packages, such as psycopg2-binary and cryptography wheels: the reseed reaches only the standard library's ssl;
  • ID libraries that keep a random pool or per-process state, other than the ones Gregale resets: instances restored from one snapshot can generate the same IDs. Gregale resets npm uuid (its random pool and its v1, v6 and v7 state), nanoid and bson ObjectId in Node, and bson ObjectId in Python, on every restore. Copies bundled into one file by esbuild or webpack, ES modules on Node older than 22.15, and Go libraries are not reset: Go rs/xid, the MongoDB Go driver's ObjectID and the OpenTelemetry Go SDK's trace IDs repeat, and Gregale logs a warning on each wake of a Go app that uses them.

A restore moves the app's clock forward by the time it spent parked. gunicorn would read that as hung workers and restart one on every wake; Gregale's Python preload stops that, and a worker that really hangs is still restarted after --timeout. Set GREGALE_GUNICORN_FREEZE_GUARD=off to turn this off.

Setting GREGALE_RESTORE_RESEED=off in the app's environment disables the Node, Python and Java reseed. Only do that for an app that never generates tokens, keys, nonces or identifiers.

Support boundaries

Compose project services may use prebuilt image: references without a build context. Stateless images join the deployment and dependency graph; database and cache images remain managed-resource requirements. Scan plans display the image declaration, and the image worker resolves tags to immutable references before materialization. The first published TCP container target selects the main port, and Compose commands retain the image ENTRYPOINT. Image workloads return a deployment ID without a build ID. Source-defined operations on these workloads currently require an atomic image admission path and are rejected. After CI pushes an image, the image-published trigger deploys its exact digest with durable per-workload and scope deduplication. New project image deployments also capture their accepted Compose CMD contract; queued images and retries retain it after app configuration changes. Historical deployments without that record keep their existing command behavior.

Compose depends_on: {backend: {condition: service_healthy}} now holds the dependent workload's initial release until the captured backend deployment is live with traffic in the same environment. A failed dependency or a fixed 15-minute wait deadline fails the candidate while the previous release keeps serving. gregale release get and the dashboard stage summary show the blocker. This gates release activation; candidate processes can boot while waiting. Declarations allow at most 100 dependency conditions per workload. Optional healthy dependencies and healthy job targets are rejected. A healthy gate on a Compose datastore such as postgres is accepted as a plain dependency, and a service_completed_successfully dependency runs as the release command of the waiting service that shares its build (multi-service apps).

Compose healthcheck: overrides are also retained for prebuilt image workloads:

yaml
services:
  api:
    image: ghcr.io/team/api:production
    healthcheck:
      test: [CMD-SHELL, 'curl -f http://localhost:${PORT}/ready || exit 1']
      interval: 15s
      timeout: 250ms
      start_period: 20s
      start_interval: 500ms
      retries: 3

String tests use CMD-SHELL; list tests accept CMD, CMD-SHELL, or NONE. disable: true disables an inherited image check. Omitted or zero timing/retry values and empty tests inherit image settings. Durations preserve exact timing; positive values must be at least 1ms. $ preserves a dollar for the guest command; scanning does not read the host environment to interpolate variables. The check runs inside the image and requires its executable or shell to exist. Accepted overrides, including the choice to inherit, survive app edits, retries, and rollback. JSON scan plans expose them as image_healthcheck.

Newly assembled image deployments require a fresh successful command check before serving readiness, alongside the existing network or worker readiness and public-route verification. Startup grace, retries, and command timeouts apply within the startup deadline. A failed or missing result blocks promotion; boot, restore, and warm-pool resume cannot reuse a previous pass. NONE and absent checks retain ordinary readiness. Redeploy to add this gate to an existing deployment. Compose dependency release gates are described above. A Compose healthcheck on a source-built service is merged onto the built image's HEALTHCHECK and enforced the same way. A Dockerfile HEALTHCHECK on its own is enforced too: a source build's next deployment waits for its command check to pass, and recovers from repeated failures, like a pushed image. The check runs inside the built image, so the tools it calls (curl, wget) must be installed there. To keep ordinary readiness, use HEALTHCHECK NONE, drop the instruction, or set healthcheck: {disable: true} on the Compose service. Deployments built before this change keep their readiness until they are redeployed.

A Compose healthcheck that only fetches the service's own serving port with curl or wget (curl -f http://localhost:8080/actuator/health || exit 1, or the CMD list form) runs from the platform instead: it becomes the service's HTTP readiness check on that path, with the same interval, timeout, retries and start period, and the command check (including an inherited image HEALTHCHECK) is set to NONE. The image then needs no curl or wget. A check of another port, with headers, a method other than GET, or any other shell syntax stays a command check. The plan notes each conversion.

Required primary image checks also drive runtime recovery. Each serving instance executes fresh command attempts using the effective interval, timeout, startup grace, and consecutive failure threshold. Repeated command failures request scheduler-owned teardown and cold recovery, even if HTTP stays open. The declared command replaces implicit HTTP liveness, so the image does not need a /healthz endpoint. Explicit HTTP/gRPC liveness remains additional. Successful checks clear the failure streak; process replacement and serving resume start fresh monitoring. Missing or invalid transport proof requests infrastructure recovery without consuming the app's permanent restart budget. The existing restart circuit limits repeated confirmed failures. Failure diagnostics use image_healthcheck_unhealthy without publishing command output. Image health checks are not enabled for every account yet.

Automatic image promotion also checks for newer accepted releases in the same app and environment scope. Older in-flight candidates become superseded, and GitHub-triggered images recheck their recorded source branch before cutover. Explicit rollback retains its existing behavior.

Prebuilt image services can also override the image's process:

yaml
services:
  api:
    image: ghcr.io/team/api:production
    entrypoint: [tini, --]
    command: [node, server.js]
    user: "1000:1000"
    working_dir: /srv/app
    stop_signal: SIGINT
    stop_grace_period: 20s
    env_file: [.env.production]

entrypoint replaces the image ENTRYPOINT and, as in Docker, drops its CMD, so command supplies the arguments; entrypoint: [] clears the ENTRYPOINT and needs a command. String entrypoints are split on spaces; anything with quotes or shell syntax must use the list form. user takes a name or id with an optional :group, resolved against the image's /etc/passwd and /etc/group. working_dir must be an absolute path. stop_signal accepts the signals guest-init delivers (SIGTERM, SIGINT, SIGQUIT, SIGHUP, SIGUSR1, SIGUSR2), and stop_grace_period is capped by the plan. Like commands, these overrides are captured per deployment, so queued deployments and rollbacks keep them. Source-built services take the same overrides: an entrypoint is folded into the service's start command (the entrypoint, then the command), and user, working_dir and the stop contract are applied to the built image as a Dockerfile's USER, WORKDIR and STOPSIGNAL would be.

env_file contributes variable names only. The scan lists them as required environment keys, exactly like environment:; values never leave the source, so set them with gregale env set or secrets. The project plan shows, per service, each name that will have no value in the target environment under Needs a value: names already configured on the app, supplied by --secrets-file, or set by Gregale itself (PORT, GREGALE_*) are left out.

Three more Gregale keys shape the apps a Compose file creates:

yaml
x-gregale-slug-prefix: shop-    # new apps are shop-ui, shop-cart, ...
x-gregale-public-auth: open     # or bearer; per service too
services:
  ui:
    build: ./ui
    x-gregale-startup-deadline: 90s
  • x-gregale-slug-prefix (top level) names each new app <prefix><service>, so short service names need not be unique across Gregale. Service names, and the <service>.svc.gregale addresses built from them, do not change; an app that already exists keeps its name. gregale deploy --project --prefix P does the same and wins over the file.
  • x-gregale-startup-deadline (seconds or a duration, at most 120 s) is how long a new instance may take to become ready. Without it, a healthcheck with a start_period sets it to start_period plus retries × interval (Docker's defaults: 3 and 30 s) when that is longer than the default 30 s. A lifecycle.startup_deadline_s in gregale.yaml takes precedence over the derived value. Either is capped at the plan's maximum (Free and Hobby 30 s, Pro 60 s, Scale 120 s).
  • x-gregale-public-auth (open or bearer, top level or per service) sets who may call a new app's public URL instead of the plan default; bearer needs Hobby or above.

The deadline and auth keys apply when an app is created; change an existing app with gregale app update.

A Compose file can opt in to importing the plain values of environment::

yaml
x-gregale-env-import: true
services:
  api:
    build: ./api
    environment:
      LOG_LEVEL: info                   # imported
      STRIPE_KEY: sk_test_example       # not imported: looks like a secret
      BILLING_URL: http://billing:8080  # not imported: Docker service address

A reviewed project apply (gregale deploy, the dashboard, or gregale deploy --repo … --project) writes each imported value into the service's app, in the deploy's environment, before any build starts; a GitHub push imports only the addresses of sibling services. Values are written only where the key is still unset: a value configured on the app, as a variable or a secret, is never replaced. The plan lists imported names under Imported from Compose and gives the reason for each value it skips: a secret-looking key or value, an address of another Compose service or the local machine, $ interpolation, an entry read from the host, or an empty value. Values never appear in the plan, logs or audit events. env_file values are never imported. compose.override.yaml is part of the Compose model, so its values are imported too; keep local-only settings out of an opted-in project. Without the opt-in the plan marks importable values as "plain value in Compose" and shows the line that imports them. An env file missing from the source (for example a git-ignored .env) is a warning, or silent with required: false. Quoted values, including multi-line double- or single-quoted ones, are read to their closing quote; a malformed line is reported with its file and line number and skipped.

Source-built services pass build.args and build.target to their Dockerfile build, as docker compose build does:

yaml
services:
  api:
    build:
      context: ./api
      target: production
      args:
        NODE_VERSION: 22
        APP_VERSION: ${APP_VERSION:-dev}
        SENTRY_RELEASE:

args takes the map or the list form. ${VAR} reads the source's .env, like the rest of the file; $VAR without braces is passed literally and warns. A name without a value (SENTRY_RELEASE:, or - SENTRY_RELEASE in the list form) also reads .env; when .env does not set it, the argument is left out and the Dockerfile's ARG default applies, with a warning. target must name a stage the Dockerfile declares with FROM … AS; an unknown stage fails the scan. A service whose build context has no Dockerfile builds with Railpack, so its args and target are warned and ignored. Up to 64 arguments of at most 4 KiB each are accepted (DockerfileBuildArgsMax, DockerfileBuildArgValueMaxBytes).

Each deployment keeps the arguments and target it was planned with, and changing either rebuilds instead of reusing a cached image. A public build URL with the same name as an argument wins. Build arguments end up in the image history, so keep secrets out of them and set those with gregale env set. Plans show the target and the argument names, not their values.

Build-time secrets use build.secrets:

yaml
services:
  api:
    build:
      context: ./api
      secrets: [npm_token]          # RUN --mount=type=secret,id=npm_token ...
secrets:
  npm_token:
    environment: NPM_TOKEN          # gregale env set NPM_TOKEN

Each entry names a top-level secret declared with environment: NAME; the build mounts the secret the app receives as NAME at runtime, under the id the entry gives ({source, target} sets the id to target). That is the app's own secret in the deployment's scope, an environment reference that points NAME at another secret, or a project environment secret the app inherits. A deployment with an explicit secret selection inherits no project secrets, at build or at runtime. file: and external secrets are not uploaded and are left out with a warning. The value is opened only inside the builder VM, mounted with BuildKit's secret mount, and never stored in the image, its cache or Gregale's records; a build whose secret is not set fails with its name. Builds with secrets run on a fresh builder. At most 16 secrets per build (DockerfileBuildSecretsMax).

A service's own secrets become files in /run/secrets:

yaml
services:
  db-client:
    image: example/app:1
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password                 # /run/secrets/db_password, mode 0444
      - source: api_key
        target: api.key             # /run/secrets/api.key
        mode: 0400
secrets:
  db_password:
    environment: DB_PASSWORD        # gregale env set DB_PASSWORD
  api_key:
    environment: API_KEY

Each entry names a top-level secret declared with environment: NAME; the file holds the secret the app receives as NAME, which is also in its environment. target is a file name in /run/secrets (an absolute path there is the same); a target elsewhere, a file: or external source is left out with a warning, and an undeclared name fails the scan. mode defaults to 0444; the file is owned by the user the service runs as, and uid/gid are ignored. The files live in a memory-backed /run/secrets written before the service starts. An image that opts into live secret reload gets them rewritten with each new value; otherwise they change on the next start. A secret that is not set has no file. Only the service's main process gets the files, not sidecars, jobs or app tasks. At most 16 files per service (SecretFilesMax).

A service's size and count set its app's settings:

yaml
services:
  api:
    image: example/api:1
    deploy:
      replicas: 3                   # max_concurrency 3 (instances still park when idle)
      resources:
        limits:
          memory: 512M              # ram_mb 512
          cpus: "0.5"               # cpu_millicores 500

memory (or mem_limit) takes bytes or a k, m, g suffix in powers of 1024 and is rounded up to whole MiB; more than the plan's RAM per app fails the plan. cpus (or the service-level cpus) is rounded up to an app CPU share, 0.25, 0.5 or 1, with a warning; more than 1 is lowered to 1. replicas (or scale) caps a request-mode app's instances and fixes a worker's or service's replica count, within the plan's cap for that mode; it does not apply to jobs, and replicas: 0 is ignored with a warning. Declared values are written on every apply and replace values set with gregale app <slug> --ram and the like; settings the file does not declare keep the app's. Reservations and the other deploy keys are warned.

A new service whose file declares no memory starts with 128 MB (ProjectWorkloadDefaultRAMMB), not the default a standalone app gets (the plan's RAM, at most 1024 MB). The project plan marks such services memory=128MB (default) and lists them under "Starts with the default 128 MB". Node and Python services often need more, so declare memory, or raise it with gregale app <slug> --ram after the deploy.

extends and top-level include are resolved as Compose resolves them:

yaml
include:
  - services/api/compose.yaml        # build: . there builds services/api
services:
  worker:
    extends: {file: common/base.yaml, service: node}
    command: [node, worker.js]

A service is merged onto its base with the override-file rules: mappings merge, ports, env_file, profiles, depends_on and environment append, and other values are replaced. Build contexts and env_file paths in another directory stay relative to their own file. Included services join the project; a service defined in two files, an unknown base, a cycle or a missing file fails the scan, as in Compose. Remote includes are not loaded and warn. An included file is interpolated with its own values: the including project's, overlaid by the files its env_file option names (from the including file's directory; a missing one fails the scan), or else by the .env beside the included file. COMPOSE_PROFILES is read from the root .env only. An include's project_directory is not applied and warns; paths resolve from the included file's directory. At most 32 files are linked in one scan.

A service with profiles: is deployed only when one of its profiles is active. Activate profiles with COMPOSE_PROFILES in the source's .env, as Compose reads it there: comma-separated names, or * for every profile. Other services are skipped with a warning naming their profiles.

The scan reports every other Compose key instead of dropping it silently:

KeysResult
build (context, dockerfile, args, target, secrets), command, cpus, depends_on, deploy (replicas, resources.limits.memory, resources.limits.cpus), entrypoint, expose, healthcheck, image, mem_limit, ports, profiles, scale, secrets (environment: sources), stop_grace_period, stop_signal, user, working_dir, x-gregale-*Applied.
environment, env_fileNames applied: the plan lists each one without a value under Needs a value. Plain environment: values are imported only with x-gregale-env-import: true, on a reviewed deploy; env_file values are never imported. See above.
container_name, init, stdin_open, tty, platform: linux/amd64, x-* extensionsIgnored without a warning; they have no effect on a microVM service.
volumes, tmpfsWarning: no persistent volumes or bind mounts; each start gets a fresh filesystem.
Other deploy keys (restart_policy, placement, update_config, resources.reservations, …), cpu_shares, cpu_quota, cpuset, mem_reservation, memswap_limitWarning, with the reason for each.
restartWarning: the platform starts, parks and restarts services.
configsWarning: build the file into the image or use environment variables.
networks, network_mode, links, external_linksWarning: services reach each other through depends_on service bindings.
cap_add, privileged, devices, security_opt, ulimits and other kernel controlsWarning: each service runs in its own microVM.
dns, extra_hosts, hostname and other guest networking keysWarning: guest networking is managed by the platform.
labels, logging, pull_policy, any other platformWarning.
build.ssh, build.dockerfile_inline, other build.* keysWarning: the builder uses only build.context, build.dockerfile, build.args, build.target and build.secrets.
Any other service keyWarning: not supported.

Managed database and cache services (for example postgres) do not report their keys: the managed resource replaces the container.

ConcernCurrent contractQualification boundary
Image platformLinux/amd64; compatible child selected from an OCI or Docker index. A lone child without a platform annotation is selected and its config's platform checked.Other architectures and operating systems are rejected.
ProcessImage ENTRYPOINT + CMD, environment, working directory, and user. As under Docker, an image without USER runs as root, and a numeric UID absent from the image's passwd runs with GID 0. Root-owned image files stay root-owned in the guest.Metadata inspection cannot prove executables or users exist in the layers. Numeric or named USER user:group is preserved; explicit missing identities fail launch. Supplementary memberships are not imported. Redeploy older deployments to pick up root ownership.
Main listenerExplicit deployment port, otherwise one exposed TCP port, otherwise 8080. Port 80 is supported: when a workload in the VM declares it, the in-guest metadata endpoint moves from 169.254.169.254:80 to 169.254.169.254:8775.Multiple TCP declarations do not select the main port. Bind to 0.0.0.0. Read the metadata URLs from FAAS_EVENT_PUBLISH_ENDPOINT, FAAS_METADATA_ENV_ENDPOINT and FAAS_SECRETS_RELOAD_ACK_ENDPOINT instead of hardcoding the address.
Additional listenersDeclared TCP listeners use <slug>--port-<name>.<apps-domain> selectors through the gatewayThese are HTTP gateway selectors. Raw TCP uses separately configured app-owned listeners; UDP uses the separate opt-in listener service below.
Raw TCP ingressOpt-in public edge binds stable app-owned TCP listener ports and forwards bytes to the app; optional per-listener TLS terminationNot enabled for every account yet. TLS defaults to passthrough; termination requires a verified app-owned hostname.
Private TCP between servicesSame-account services dial <name>.svc.gregale:<port>, or the bare Compose name (orders:8080, which the guest resolver searches under svc.gregale), on any declared TCP listener or the serving port; compose expose: declares internal-only listenersNot enabled for every account yet; until it is, service names answer HTTP only. Internal listeners never get public selectors or raw TCP listeners. Ports 10080, 10081 and 443 stay on the HTTP mesh. See networking.
Raw UDP ingressOpt-in public edge reserves app-owned UDP endpoints and forwards framed datagrams to the appNot enabled for every account yet; requires IPv4 source CIDRs.
Host portsDurable per-node TCP/UDP lease allocationA lease does not bind a socket or enable direct ingress.
ReadinessTCP by default for direct images; explicit health path selects HTTPImage HEALTHCHECK metadata is separate from verifying public-route readiness.
Image healthchecksCMD/CMD-SHELL polling with image identity, environment, working directory, and exact nanosecond timing; StartInterval is retainedCMD-SHELL requires the image to contain its shell. Not enabled for every account yet.
FilesystemCompatible shared-base layering or full-rootfs fallback; ephemeral writable stateVOLUME does not provision persistent storage; no host mounts or Docker socket.
LifecycleRequest, service, worker, and job modes with validated restart policiesFree is request-only; quotas and availability remain plan-controlled.
CompanionsSeparate image roots and resource controls, shared guest kernel and loopbackUse separate deployments for mutually untrusted workloads.
Snapshot restoreRestorable cache with cold-boot fallback; optional lifecycle callbacksExternal connections and durable state require application recovery handling.

Availability is defined by the capability matrix, not by this compatibility table. In particular, container deployment is generally available while companions and worker pools are preview.

Image preflight

During self-contained full-rootfs assembly, Gregale checks the effective startup command after applying all image layers and deployment command overrides. An explicit command path must resolve to a regular file with an execute bit; relative paths resolve from the image working directory. Shell-form startup commands therefore require their selected shell (usually /bin/sh) in the image. Missing commands, invalid symlinks, directories, and non-executable files fail the deployment with image_manifest_invalid before ext4 publication or VM boot. The failure identifies the command without exposing arguments or environment values.

For bare commands, assembly uses the image/deployment PATH plus the current scoped app environment, with the same absolute-directory lookup as guest-init. A sealed PATH or unavailable runtime environment defers that lookup to the guest. Assembly never decrypts secrets or copies runtime PATH into the image. Later environment changes remain subject to guest launch validation. Commands under guest-provided mounts (/dev, /proc, /sys, /tmp, and companion roots), including image symlinks to those paths, also defer to launch because their contents are supplied or replaced at boot.

This check does not run image code or prove ELF/script interpreter compatibility, user permissions, healthcheck execution, shell command contents, or readiness. It applies to the complete full-rootfs main image; the shared-base upper-layer path cannot prove whether a command exists in its base and retains its guest validation. The metadata-only doctor command below retains its fast path.

gregale doctor --image REF --json reports image.serving_port as inferred from image metadata before deployment overrides. Human output shows the same port. A listener finding warns when multiple TCP ports leave the default ambiguous or when only UDP ports are declared. --strict makes those warnings fail the preflight; normal mode reports them without rejecting the image. An image exceeding the workload listener cap fails runtime-contract validation. Declared volume paths appear in image.volume_paths and human output, with an explicit warning that they remain ephemeral and do not provision durable storage. UDP-only images receive guidance for configuring app-owned UDP endpoints and source CIDRs; a declaration alone does not enable ingress or provide the main HTTP readiness listener.

Preflight does not download layers, execute image commands, prove that the server binds its port, or validate account policy. A successful metadata check does not prove the image runs.

Spotted a problem on this page? Tell us