Compose Compatibility

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 field	Notes
`services.<name>.image`	Required — used as OCI image reference
`services.<name>.command`	Maps to container command override
`services.<name>.entrypoint`	Maps to container entrypoint
`services.<name>.environment`	Maps to service env vars
`services.<name>.env_file`	Resolved at import time, merged into env
`services.<name>.ports`	Short and long syntax; mapped to port exposure model
`services.<name>.volumes` (named)	Named volumes map to state volumes
`services.<name>.working_dir`	Maps to container working directory
`services.<name>.user`	Maps to container user
`services.<name>.restart`	Mapped to restart policy
`services.<name>.healthcheck`	Maps to health check configuration
`services.<name>.labels`	Preserved as service labels
`volumes` (top-level named)	Created as project-scoped named volumes

Supported with transformation

Compose field	Transformation
`services.<name>.build`	Rejected 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_on`	Simple form → startup ordering; extended form (`condition: service_healthy`) → ordering + health check gate
`services.<name>.networks`	Custom networks collapsed into the single project network; service aliases preserved
`services.<name>.expose`	Treated as internal-only port declaration (no host exposure)
`services.<name>.tmpfs`	Mapped to in-memory tmpfs mount inside the container
`services.<name>.logging`	Driver-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 field	Reason
`services.<name>.privileged`	No privileged containers in v1
`services.<name>.cap_add`	Capabilities are dropped by default; adding is not permitted
`services.<name>.pid`	No host PID namespace sharing
`services.<name>.network_mode: host`	No host network mode in VM context
`services.<name>.devices`	No device passthrough in v1
`services.<name>.sysctls`	No sysctl modification in v1
`services.<name>.security_opt`	Managed by runtime hardening
`services.<name>.deploy`	Swarm/orchestration directives ignored
`services.<name>.configs`	Use env vars or mounted files instead
`services.<name>.secrets` (Docker secrets)	Use Vibe secret model (Keychain or encrypted package)
`services.<name>.extends`	Service inheritance not supported
`services.<name>.profiles`	Profile-based service activation not supported
`networks` (top-level custom)	Complex network topologies collapsed

Import pipeline

The Compose import runs 7 steps:

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

Overview

Getting Started

Manifest Reference

CLI Reference

Security

Internals

Compose Compatibility

Overview

Field support matrix

Supported (direct mapping)

Supported with transformation

Rejected

Import pipeline

Common transformations

Relative bind mounts

`depends_on`

nerdctl Compose

​Overview

​Field support matrix

​Supported (direct mapping)

​Supported with transformation

​Rejected

​Import pipeline

​Common transformations

​Relative bind mounts

​depends_on

​nerdctl Compose

Overview

Field support matrix

Supported (direct mapping)

Supported with transformation

Rejected

Import pipeline

Common transformations

Relative bind mounts

`depends_on`

nerdctl Compose