coma.yaml

A coma.yaml makes a project directory a workspace: it names the machine, the engine, what to sync and which ports to forward. It is meant to be committed. coma workspace init writes a minimal one; coma workspace validate checks it.

Complete exampleCopy Anchor Link

apiVersion: coma.sh/v1alpha1
kind: Workspace
metadata:
  name: shop
  description: Storefront and its database
  labels:
    team: web
spec:
  source:
    path: .
  target:
    machine: dev
  runtime:
    engine: docker
    compose:
      files:
        - compose.yaml
      projectName: shop
  sync:
    mode: one-way-safe
    gitignore: true
    ignore:
      - node_modules/
      - "*.log"
    include:
      - .env.development
  ports:
    - name: web
      remote: 3000
    - name: db
      remote: 5432
      local: 15432
    - service: web
      remote: 80
      local: auto
    - name: redis
      remote: 6379
      local: disabled

Finding the fileCopy Anchor Link

Workspace commands use --file when given. Otherwise they look for coma.yaml or coma.yml in the current directory, then in each parent, and stop at the repository root (a directory containing .git) or the filesystem root. A directory with both names is an error (workspace_manifest_ambiguous). A manifest may be at most 1 MiB, and each list at most 256 entries.

ValidationCopy Anchor Link

Unknown keys and wrong types are errors, reported with the file and line. Once the file decodes, every field error is reported together, with its line, column and YAML path:

coma workspace validate

Error: ./coma.yaml is not a valid workspace manifest:
  ./coma.yaml:4:9 metadata.name: "Bad_Name" must be lower-case letters, digits and dashes (at most 63)
  ./coma.yaml:6:5 metadata.labels: label "coma.sh/x" uses the reserved coma.sh/ prefix
  ./coma.yaml:13:19 spec.ports.0.visibility: public visibility is not supported: COMA never opens public ingress (workspace_manifest_invalid)

An invalid manifest exits with 2 (workspace_manifest_invalid). With --json, each problem is in error.details.diagnostics with file, line, column, path and message.

coma workspace status reports drift when coma.yaml changed after the last coma workspace up.

Top levelCopy Anchor Link

The older name coma.dev/v1alpha1 is still read, with a warning to change it. Any other apiVersion fails with workspace_api_version_unsupported (exit 8).

metadataCopy Anchor Link

coma workspace init derives the name from the directory's name.

spec.sourceCopy Anchor Link

spec.targetCopy Anchor Link

Set at most one of the three. Machine names are per user, so coma workspace init writes machine only when you pass --machine.

The machine is chosen in this order: --machine, then spec.target.machine, then the current context's machine. With none of them, plan and up fail with workspace_target_required. coma workspace plan shows which one was used.

spec.runtimeCopy Anchor Link

The engine is chosen in this order: --engine, then spec.runtime.engine, then the current context's preference or the machine's only working engine.

COMA does not start Compose: you run docker compose up after coma workspace up. files, profiles, envFiles and removeOrphans are accepted and their paths checked, but COMA does not pass them to Compose. projectName matters now: it is the project in which spec.ports entries with service find their containers. Without it, COMA uses Compose's default, the name of the source directory (or workingDirectory), lower-cased, keeping letters, digits, - and _.

spec.syncCopy Anchor Link

Sync modesCopy Anchor Link

A repository's coma.yaml alone cannot make changes on the machine flow back to your computer: without your setting, bidirectional blocks up with workspace_plan_blocked. Both opt-in modes need the Mutagen sync engine; otherwise up fails with sync_mode_unsupported. coma workspace up --no-sync skips sync for one run. See Source sync.

Ignore rulesCopy Anchor Link

ignore and include entries are Git-style patterns relative to the source directory. Each must be one line of at most 1,024 bytes, not empty, not a comment, and must not leave the source directory (..).

Rules apply in this order, later rules winning: the built-in rules (.git/ and .coma/), .comaignore, the root .gitignore, ignore, include, then nested .gitignore files. As in Git, include cannot bring back a path inside a directory that is excluded. gitignore: false drops the .gitignore files; the built-in rules and .comaignore still apply.

coma sync explain <path> says whether a path is synced and which rule decided.

Fields reported as unsupportedCopy Anchor Link

spec.portsCopy Anchor Link

Each entry forwards a port on the machine to your computer, possibly at another number. While the workspace is up, a declared port replaces the automatic mirror of the same remote port. See Ports.

Names, explicit local ports and forwarded targets must each be unique within the file. A local port that is busy on your computer, or declared by another workspace, is reported as local_port_in_use; coma port list shows the state of each port.

Reserved sectionsCopy Anchor Link

These spec sections are accepted with any content but not implemented yet. coma workspace validate and plan list each one as "not implemented yet, ignored", so nothing is silently dropped:

requirements, environment, secrets, persistence, caches, lifecycle, idle, budget, policy, extensions.