wendy.json

wendy.json is the configuration file for a Wendy app. It lives at the root of your project and describes the app's identity, target platform, required capabilities, and runtime behaviour.

Example

{
  "$schema": "https://wendy.dev/schemas/wendy.json",
  "appId": "my-app",
  "platform": "linux",
  "version": "1.0.0",
  "language": "swift",
  "entitlements": [
    { "type": "network" },
    { "type": "gpu" }
  ]
}

Fields

appId (required)

Unique identifier for the app.

{ "appId": "my-app", "platform": "linux" }

version

Version string for the app, e.g. "1.0.0".

platform

Target platform. One of:

Use "linux" for WendyOS/Linux container targets. Omit to target the default Linux platform. Existing "wendyos" configs are accepted as an alias and resolve to linux before Docker or Apple Container builds.

Use "darwin" for native macOS targets managed by Headless Mac. The CLI builds the app on a Mac development machine, syncs the build output to the Mac agent, and launches it as a native macOS process. Darwin apps run natively and non-containerized; they do not use the WendyOS Linux container runtime.

Headless Mac: If the selected target is Headless Mac, wendy run rejects any platform value that does not resolve to darwin (for example, linux/arm64 or wendyos). Set platform: "darwin" and use a native SwiftPM or Xcode project.

Minimal SwiftPM/Linux container configuration:

{
  "$schema": "https://wendy.dev/schemas/wendy.json",
  "appId": "com.example.hello-linux",
  "version": "1.0.0",
  "language": "swift",
  "platform": "linux"
}

language

Project language, e.g. "swift" or "python". Used by the CLI to select the appropriate build toolchain.

debug

Set to true to enable debug mode (default false). Injects debug tooling into the container via the WENDY_DEBUG build arg.

brewfile

Optional Homebrew Bundle manifest for native macOS (platform: "darwin") deployments. The path is relative to wendy.json; absolute paths and .. components are not allowed.

{
  "platform": "darwin",
  "brewfile": "Brewfile.wendy"
}

If brewfile is omitted and a Brewfile.wendy exists at the project root, wendy run auto-detects it for native SwiftPM and Xcode Mac deployments. A plain project-root Brewfile is left for developer-machine setup and is not applied to the target unless explicitly referenced. The CLI syncs the Wendy Brewfile to the target Mac and Wendy Agent runs brew bundle --file <synced Brewfile> before starting the app. Homebrew must already be installed on the target Mac; Wendy does not install Homebrew automatically. Linux/WendyOS container deployments ignore Brewfiles.

entitlements

Array of capabilities the app requires. See Entitlements below.

readiness

Configures how the CLI determines when the app is ready after starting.

{
  "readiness": {
    "tcpSocket": { "port": 8080 },
    "timeoutSeconds": 30
  }
}

For multi-service apps, declare readiness per service under services.<name>.readiness instead of (or in addition to) the top-level field. A top-level readiness becomes an app-level fallback that fires once after every service has started, rather than gating any single service — see Readiness and lifecycle hooks for the full scoping and attached/detached rules.

hooks

Lifecycle commands to run at specific points during the app lifecycle.

{
  "hooks": {
    "postStart": {
      "openURL": "http://${WENDY_HOSTNAME}:8080",
      "agent": "/app/post-start.sh"
    }
  }
}

Prefer openURL over a cli command that shells out to a platform-specific opener (open, xdg-open, start) — those only work on one OS, and the CLI warns about them, suggesting openURL instead. When both are set, openURL fires first, then cli runs.

Note: hooks.postStart.agent is executed directly on the device, not through a shell. Shell features such as pipes (|), redirects (>), command chaining (;, &&), and command substitution ($(...)) are not interpreted — they are passed through as literal arguments. If you need them, put the logic in a script file (e.g. /app/post-start.sh) and invoke that. ${WENDY_APP_ID}, ${WENDY_HOSTNAME}, ${WENDY_SERVICE_NAME} (the declaring service's name; empty for single-container apps), and environment variables are still expanded.

For multi-service apps, declare hooks per service under services.<name>.hooks instead of (or in addition to) the top-level field. A top-level hooks becomes an app-level fallback that fires once after every service has started; its postStart.agent is ignored for multi-service apps, since there is no app-level container to run it in — wendy run warns about this when it loads wendy.json. See Readiness and lifecycle hooks for the full scoping and attached/detached rules.

python

Python-specific settings.

resources

Optional CPU, memory, and process-count ceilings the agent enforces on the container via cgroups. Edge devices are resource-constrained and often run several apps side by side, so capping a service keeps one busy or leaky app from starving its neighbours. Every field is optional. Omitting memory or cpus leaves that resource unbounded (the historical behaviour), so adding resources is backward compatible. pids is the exception: when omitted, a conservative default ceiling (4096) is applied as a fork-bomb guard — set it explicitly to raise or lower that ceiling.

{
  "resources": {
    "memory": "512Mi",
    "cpus": "1.5",
    "pids": 256
  }
}

For multi-service apps, set resources at the top level as the default and/or per service under services.<name>.resources. App-level and service-level limits are merged per field: a field a service sets wins, and a field it leaves unset inherits the app-level value. This means a service can override one limit without silently dropping the others (e.g. an app-level PID cap stays in force even if a service only changes memory).

{
  "appId": "fleet",
  "resources": { "memory": "1Gi", "pids": 512 },
  "services": {
    "web":    { "context": "./web" },
    "worker": { "context": "./worker", "resources": { "memory": "256Mi", "cpus": "0.5" } }
  }
}

Here web inherits the full app-level limits (1Gi, pids: 512). worker uses its own 256Mi and 0.5 cores, and still inherits the app-level pids: 512 it did not override.

$schema

Optional URI pointing to the JSON Schema for editor autocompletion and validation. Set to "https://wendy.dev/schemas/wendy.json".

Entitlements

Entitlements grant the app access to hardware and system capabilities. Any capability not listed is unavailable to the app. They are code signed, preventing privilege escalation.

Use wendy project entitlements add / remove to manage them, or edit wendy.json directly.

network

IP networking access.

{ "type": "network" }
{ "type": "network", "mode": "host" }
{ "type": "network", "mode": "bridge" }

Security note: CAP_NET_ADMIN (host network reconfiguration) is granted only by "host-admin", never by plain "host". Apps that previously relied on CAP_NET_ADMIN under "host" must switch to "host-admin".

Deprecation notice: an omitted mode maps to host networking today, and the agent logs a WARN at container create for any network entitlement without an explicit mode, flagging that its ports are publicly reachable. This default will change to isolated "bridge" networking in a future major release. If you want to keep host networking going forward, set "mode": "host" explicitly now; if you want isolated networking with outbound internet, opt in early with "mode": "bridge".

gpu

Hardware-dependent GPU or board-telemetry access.

{ "type": "gpu" }

On Raspberry Pi, /dev/vcio is bind-mounted only when present on the host; access is rw (no mknod).

camera

Camera / V4L2 device access.

{ "type": "camera" }
{ "type": "camera", "allowlist": ["/dev/video0"] }

audio

Microphone and speaker access.

{ "type": "audio" }

bluetooth

Bluetooth access.

{ "type": "bluetooth" }

persist

Persistent storage that survives container restarts.

{
  "type": "persist",
  "name": "my-app",
  "path": "/data"
}

usb

USB device access.

{ "type": "usb" }

i2c

I2C bus access.

{ "type": "i2c", "device": "/dev/i2c-1" }

serial

Serial tty (UART) device access — e.g. a USB-serial adapter or servo bus (pyserial/termios). This is how apps do UART. See the Serial / UART guide.

{ "type": "serial", "device": "ttyACM0" }

gpio

GPIO pin access.

{ "type": "gpio" }
{ "type": "gpio", "pins": [17, 27] }

spi

SPI device access via spidev (/dev/spidev<bus>.<chipselect>). Takes no options — grants the SPI subsystem as a whole. See the SPI guide.

{ "type": "spi" }

Security note: unlike serial/i2c (scoped to one node's major:minor), spi is a whole-major grant — an app with it can reach every SPI bus on the host.

input

HID input device access (barcode scanners, keyboards, etc.).

{ "type": "input" }

mcp

Registers the container as a Model Context Protocol (MCP) server. When this entitlement is present the wendy agent:

1. Stores the port in the container's sh.wendy/mcp.port label.
2. Exposes the container's tools through wendy mcp serve so that AI assistants (Claude Desktop, etc.) can call them automatically.
3. Makes the port available via the StreamMCP gRPC API for secure proxying.

{ "type": "mcp", "port": 3000 }

The container must serve the MCP Streamable HTTP transport on 0.0.0.0:<port>. See the MCPExample for a complete Python reference implementation.

Note: The mcp entitlement is typically combined with { "type": "network", "mode": "host" } so that the agent can reach the container's MCP port over loopback.

display

Present to a locally-attached monitor as a Wayland client (GPU-accelerated) — the app or shell draws directly to the screen, no web browser involved.

{ "type": "display" }

The container receives:

• /dev/dri (GPU render nodes); cgroup access is rw, no mknod.
• Membership in the video and render groups.
• The WendyOS compositor's Wayland socket, exposed via WAYLAND_DISPLAY / XDG_RUNTIME_DIR.

On NVIDIA Jetson the GL/EGL userspace is injected from the host through the same CDI path as gpu; on Raspberry Pi the app's own mesa works against the vc4 kernel driver.

Security: apps without display never receive /dev/dri — the default GPU/display sandbox is unchanged.

admin

Grants the container the wendy-agent's full gRPC over a local unix socket (/run/wendy/agent.sock, exposed as WENDY_AGENT_SOCKET) — with no authentication.

{ "type": "admin" }

An app with admin can start, stop, and delete apps and read all device data locally. The socket is bind-mounted only into containers that declare admin — that mount is the entire trust boundary — and it is never reachable off-device (a unix socket, not TCP). At most one admin per app.

Security: admin is a privileged, deliberate grant equivalent to local device control. Grant it only to fully-trusted first-party apps (e.g. the WendyOS shell). Requires an agent build that serves the local socket.

Compose-based projects

If your project uses a docker-compose.yml instead of a single container, you don't need a wendy.json. wendy run detects the compose file automatically and each service gets a generated app config derived from its ports, network_mode, and volumes declarations.

See Multi-Service Apps with Docker Compose for details.

Deprecated: { "type": "video" } — use camera instead.