Multi-Service Apps with wendy.json

When your project needs more than one container managed through a wendy.json file (rather than a docker-compose.yml), declare a services map in wendy.json. wendy run detects the map and automatically orchestrates a parallel multi-service build and deployment.

wendy.json structure

{
  "appId": "com.example.myapp",
  "platform": "linux",
  "services": {
    "db": {
      "context": "db"
    },
    "api": {
      "context": "api",
      "dependsOn": ["db"],
      "entitlements": [
        { "type": "network", "mode": "host" }
      ]
    },
    "frontend": {
      "context": "frontend",
      "dependsOn": ["api"]
    }
  }
}

services map

Each key is a service name. Each value is a ServiceConfig object:

Validation rules

wendy.json validation rejects the following:

• A service with an empty or missing context.
• A context that is an absolute path.
• A context that contains .. path components.
• A dependsOn entry that references a service name not present in the services map.
• A service entitlements entry with an unknown or missing type.
• A service persist entitlement missing name or path, or with a non-absolute or ..-containing path.
• A service network entitlement with a mode other than "host" or "none".
• A service i2c entitlement with a device not in i2c-N format.
• A service serial entitlement with a device not matching the USB-only ttyACM0 / ttyUSB0 (tty*N) pattern.
• A service mcp entitlement with a port outside the range 1–65535.
• More than one mcp entitlement within a single service's entitlements array.

ValidateJSON additionally warns on deprecated entitlement types and unknown entitlement keys within service-level entitlements arrays, using the same rules applied to the top-level entitlements field.

Readiness and lifecycle hooks

Any service in the services map may declare its own readiness probe and hooks.postStart, using the same schema as the top-level readiness/hooks fields:

{
  "appId": "com.example.stack",
  "services": {
    "db": { "context": "db" },
    "cache": { "context": "cache" },
    "api": { "context": "api", "dependsOn": ["db", "cache"] },
    "frontend": {
      "context": "frontend",
      "dependsOn": ["api"],
      "readiness": {
        "tcpSocket": { "port": 3000 },
        "timeoutSeconds": 30
      },
      "hooks": {
        "postStart": {
          "openURL": "http://${WENDY_HOSTNAME}:3000"
        }
      }
    }
  }
}

Only a service that declares readiness or hooks runs the readiness→postStart sequence; db, cache, and api above are unaffected.

Scoping

• readiness gates only the declaring service's own postStart hook — it never delays other services' startup order (dependsOn ordering is a separate mechanism).
• hooks.postStart.agent (a command run on the device) is delivered only to the declaring service's own container start call; it never runs in any other service's container.
• Hook commands may reference ${WENDY_HOSTNAME} (the device host), ${WENDY_APP_ID}, and ${WENDY_SERVICE_NAME} — the declaring service's name, empty for single-container apps and for the app-level fallback below. Windows-style %VAR% forms are accepted too.

App-level fallback

A top-level readiness/hooks in wendy.json acts as an app-level fallback: it fires once after every service has started, rather than gating any single service. Both the fallback and a service's own readiness/hooks fire if both are declared. Two exceptions:

• A top-level hooks.postStart.agent is ignored for multi-service apps — there is no app-level container to run it in. wendy run warns about this when it loads wendy.json; declare it under services.<name>.hooks instead.
• The fallback is skipped when wendy run --service selects a subset of services, since "every service has started" can't be guaranteed on a partial run.

Attached vs. detached

In attached mode, each service's readiness→postStart sequence fires asynchronously right after that service's start is acknowledged, so a slow or failing probe never delays starting the next service. Ctrl-C cancels any in-flight readiness wait and kills cli hook child processes. If the run ends on its own — every service's log stream closes — while a hook (per-service or the app-level fallback) is still waiting on readiness, that hook is suppressed rather than fired, so wendy run never opens a browser onto a stack that has already exited. In detached mode, readiness is waited sequentially in dependency order after every service has started; hooks outlive the CLI once it exits, and a readiness failure only prints a warning — it never fails the command.

How wendy run handles multi-service projects

When appCfg.Services is non-empty, wendy run routes to the multi-service pipeline:

1. Parallel build — all service images are built and pushed concurrently. By default, up to 4 simultaneous builds run; for large groups (8+ services), builds throttle to 2 concurrent to protect the device registry tunnel. Override with --max-concurrency. In interactive terminals a per-service spinner displays each service's status (waiting → building… → built (Xs) / failed). In non-interactive terminals plain log lines are printed instead.
2. Ordered container creation — containers are created one at a time in topological dependency order. A service listed in another service's dependsOn is created first.
3. Start and stream — all containers are started and their combined stdout/stderr is multiplexed to the terminal. Each line is prefixed with [serviceName].

Press Ctrl-C to stop all services. The CLI cancels all streams, issues a StopContainer for each service concurrently, and waits up to 30 seconds before exiting.

Container naming

Each service container ID follows the {appId}_{serviceName} convention (_ is the separator because / is not permitted in containerd container IDs). For example, with appId: "com.example.myapp" and service "api", the containerd container ID is com.example.myapp_api. The corresponding snapshot key uses @ as the separator (wendy-com.example.myapp@api) to remain unambiguous when either component contains a hyphen. The cgroup path component uses @ as the separator: system.slice:edge-agent:com.example.myapp@api (the systemd service segment reflects the WENDY_SYSTEMD_SERVICE_NAME env var, which defaults to edge-agent; @ is used because it cannot appear in either a valid appId or serviceName, eliminating any collision risk from the hyphen separator).

Note: Single-container apps (no serviceName in the top-level wendy.json) are unaffected — their container ID remains the bare appId.

Filtering with --service

To build and run only a specific service (and its transitive dependencies):

wendy run --service api

This resolves api and all services reachable through its dependsOn graph. Services outside this subset are not built or started. Passing an unknown service name returns an error immediately.

Flags

All standard wendy run flags apply. The following are particularly relevant for multi-service projects:

Example layout

my-project/
  wendy.json
  db/
    Dockerfile
  api/
    Dockerfile
  frontend/
    Dockerfile

wendy run            # builds and starts all three services
wendy run --service api   # builds db and api only (frontend excluded)

Crash-looping services

When a service within a group crashes and the agent's restart policy is automatically restarting it, that service's individual entry in wendy device apps list shows a red ↻ crash-looping state (nested under the group header). The top-level app entry stays Running as long as at least one service is up; it flips to Crash-looping only when every service is down and the restart policy is still restarting at least one of them.

wendy device logs --app <appId> surfaces crash output from all service members of the group, so a crash-looping service's logs are reachable without naming the individual service.

Limitations

• Log output is multiplexed with a [serviceName] prefix on each line. Per-service log stream routing is not yet available.
• Containers are created via individual CreateContainer calls in dependency order. A grouped CreateAppGroup RPC for atomic creation is planned as a follow-up.
• Headless Mac is not supported. wendy run rejects multi-service wendy.json projects when the selected target is Headless Mac, before any build or registry operation. Target a Linux/WendyOS device for multi-service workloads.