> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotvibe.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Compose Compatibility

> Which Docker Compose fields Vibe supports, transforms, or rejects.

## 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:

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

```yaml theme={null}
# 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`

```yaml theme={null}
# 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.