Skip to main content

​
Overview

Vibe supports two runtime modes: native (services defined in vibe.yaml) and compose (runtime.composeFile points to a Compose file). In compose mode, the Compose file is processed through an import pipeline at runtime — not executed directly by docker compose or nerdctl compose.

​
Field support matrix

​
Supported (direct mapping)

Compose fieldNotes
services.<name>.imageRequired — used as OCI image reference
services.<name>.commandMaps to container command override
services.<name>.entrypointMaps to container entrypoint
services.<name>.environmentMaps to service env vars
services.<name>.env_fileResolved at import time, merged into env
services.<name>.portsShort and long syntax; mapped to port exposure model
services.<name>.volumes (named)Named volumes map to state volumes
services.<name>.working_dirMaps to container working directory
services.<name>.userMaps to container user
services.<name>.restartMapped to restart policy
services.<name>.healthcheckMaps to health check configuration
services.<name>.labelsPreserved as service labels
volumes (top-level named)Created as project-scoped named volumes

​
Supported with transformation

Compose fieldTransformation
services.<name>.buildRejected at runtime; developer must build the image externally and provide a registry reference
services.<name>.volumes (bind mounts)Relative host paths remapped to state/current/files/; absolute host paths rejected
services.<name>.depends_onSimple form → startup ordering; extended form (condition: service_healthy) → ordering + health check gate
services.<name>.networksCustom networks collapsed into the single project network; service aliases preserved
services.<name>.exposeTreated as internal-only port declaration (no host exposure)
services.<name>.tmpfsMapped to in-memory tmpfs mount inside the container
services.<name>.loggingDriver-specific options dropped; logs captured by the supervisor’s unified log collector

​
Rejected

These fields trigger a warning in the import report. Their presence does not block import unless marked critical.
Compose fieldReason
services.<name>.privilegedNo privileged containers in v1
services.<name>.cap_addCapabilities are dropped by default; adding is not permitted
services.<name>.pidNo host PID namespace sharing
services.<name>.network_mode: hostNo host network mode in VM context
services.<name>.devicesNo device passthrough in v1
services.<name>.sysctlsNo sysctl modification in v1
services.<name>.security_optManaged by runtime hardening
services.<name>.deploySwarm/orchestration directives ignored
services.<name>.configsUse env vars or mounted files instead
services.<name>.secrets (Docker secrets)Use Vibe secret model (Keychain or encrypted package)
services.<name>.extendsService inheritance not supported
services.<name>.profilesProfile-based service activation not supported
networks (top-level custom)Complex network topologies collapsed

​
Import pipeline

The Compose import runs 7 steps:
  1. Locate Compose file — resolve runtime.composeFile from the manifest; supports compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml
  2. Parse and validate — parse YAML; reject files that are not valid Compose syntax
  3. Normalize — expand short-form syntax (ports, volumes, environment) into canonical long form; resolve env_file references
  4. Reject unsupported fields — collect all rejected fields into the import report (warnings by default)
  5. Rewrite host-path assumptions — relative bind mounts remapped to state/current/files/<import-dir>/; absolute host paths rejected
  6. Map to internal model — convert each Compose service into the native Vibe service definition
  7. Generate import report — structured report of successes, transformations, rejections, and warnings

​
Common transformations

​
Relative bind mounts

# Compose input
volumes:
  - ./data:/app/data

# Transformed to
mounts:
  - source: state:imported-data
    target: /app/data
Contents of ./data are copied into state/current/files/imported-data/ at import time.

​
depends_on

# Simple form → startup ordering
depends_on:
  - db

# Extended form → ordering + health check gate
depends_on:
  db:
    condition: service_healthy

​
nerdctl Compose

nerdctl compose is used only as a validation oracle during development and as a debug path — never in production. All production Compose handling goes through the import pipeline above.