Run

Runs your app on a Wendy-enabled device:

1. Selects a device
2. Queries the platform and architecture of this device
3. Invokes a build using the target triple, and injects a debugger if needed
4. Uploads the artifact(s) for Linux or macOS
5. Starts the app
6. Attaches the logs if needed (when --detach is not provided)

Note: When wendy.json is absent, wendy run resolves the target device before prompting to create one. If the target is Wendy for Mac and the detected project type is unsupported, the project/target mismatch error is returned immediately without opening the config creation prompt.

Wendy for Mac — supported project types

Wendy for Mac (Darwin targets) currently runs native macOS apps only. When the selected agent reports os: darwin, wendy run rejects Linux/container deployment paths before any build, registry auth, or registry setup.

The error explains the project/target mismatch and tells you to set platform: "darwin" with a Mac-compatible native SwiftPM or Xcode project, or to target a Linux/WendyOS device. Linux container support on Mac is planned for a future release.

Image build-args

When building a Dockerfile or Containerfile project, wendy run passes the target device's hardware parameters as --build-arg values so the build file can branch on platform, GPU vendor, or CUDA version. Declare any arg you want to use with ARG:

On Apple silicon Macs with Apple's container runtime started, Wendy tries Apple Container first when --builder is omitted. If Apple Container is unavailable or the build fails, Wendy falls back to Docker. Use --builder docker to force Docker, or --builder apple-container to require Apple Container:

container system start
wendy --device my-wendy.local run

For local-only Dockerfile or Containerfile runs on the Mac itself, use wendy run --device apple-container instead. Compose projects still require the Docker provider for local runs, but compose service builds targeting a WendyOS device can use --builder apple-container.

WENDY_PLATFORM and WENDY_DEBUG are always set. The remaining args are only injected when the agent reports them, so Dockerfiles and Containerfiles can define their own ARG defaults for devices that predate the field.

Multi-service projects (wendy.json with services)

When wendy.json contains a services map, wendy run automatically switches to the multi-service path:

1. All service images are built in parallel (up to 4 concurrent builds). In an interactive terminal a per-service spinner shows build progress; in non-interactive environments plain log lines are printed instead.
2. Containers are created individually in topological dependency order (services listed in dependsOn are created first).
3. All containers are started and their logs are streamed to stdout/stderr with a [serviceName] prefix per line.

Press Ctrl-C to stop all services. A 30-second graceful shutdown window is given before the CLI exits.

Use --service <name> to build and run only a specific service and its transitive dependsOn dependencies instead of the full set.

See Multi-Service Apps with wendy.json for a full walkthrough.

Wendy for Mac: Multi-service wendy.json projects are not supported when the selected target is Wendy for Mac. wendy run returns an error immediately. Target a Linux/WendyOS device for multi-service workloads.

Compose projects

If the current directory contains a docker-compose.yml (or compose.yml) but no wendy.json, wendy run automatically runs it as a multi-service compose project. Each service is built, pushed, and started on the device in dependency order. See Multi-Service Apps with Docker Compose for full details.

Wendy for Mac: Compose projects are not supported when the selected target is Wendy for Mac. wendy run returns an error before performing any registry or Docker setup. To deploy a compose workload, target a Linux/WendyOS device. For Mac targets, use a native SwiftPM or Xcode project with platform: "darwin".

Swift Package Manager projects (macOS)

From a macOS (Darwin) SwiftPM project, target the Mac agent explicitly:

wendy run --device <hostname-or-ip>:50051

When running a Swift Package Manager project on a macOS target, wendy run:

1. Builds the project with swift build -c release (or -c debug when --debug is passed).
2. Resolves the build products directory via swift build --show-bin-path.
3. Syncs the compiled binary to the device.
4. Automatically syncs any sibling .bundle and .resources directories found in the build products directory alongside the binary, so SwiftPM resource bundles are available at runtime.
5. Syncs sandbox.sb from the project root if present, and any additional files declared under files in wendy.json.

Swift Package Manager projects — host requirements

Both the macOS-target and Linux-target Swift paths shell out to a host Swift toolchain. The following host OS requirements apply when no Dockerfile or Containerfile is present (or when --build-type=swift is set explicitly):

On a Windows host, wendy run returns an actionable error for Swift projects that would require the host toolchain. Providing a Dockerfile or Containerfile bypasses these restrictions — the build is routed through the image build path, which works on all platforms.

Flags

postStart hooks

When a postStart hook is configured in wendy.json, wendy run fires it after the app is ready.

openURL

openURL opens a URL in the developer's default browser without a shell. It works uniformly on macOS, Linux, and Windows and is the recommended way to open a URL at startup:

{
  "hooks": {
    "postStart": {
      "openURL": "http://${WENDY_HOSTNAME}:3001"
    }
  }
}

If the browser cannot be opened, a warning is printed and wendy run continues normally. openURL is fire-and-forget and does not affect the process tracked by wendy run.

cli

cli runs a free-form shell command on the developer's machine. It is dispatched through the platform shell (sh -c on Unix, cmd.exe /S /C on Windows). wendy run tracks this child process for waiting and cancellation; the returned handle is used to clean up when wendy run exits.

openURL and cli can be set together — openURL fires first, then cli is spawned.

Note: open, xdg-open, and start inside cli are platform-specific. Use openURL to open a URL portably. WendyOS warns at config load time when hooks.postStart.cli begins with one of these commands.

Hook process lifetime

On Windows, the entire process tree spawned by a cli hook — including grandchildren started via start /B — is terminated when wendy run exits or is interrupted. This is implemented using a Windows Job Object with KILL_ON_JOB_CLOSE; closing the job handle causes the kernel to terminate every process assigned to it. If Job Object creation is unavailable, wendy run falls back to taskkill /T /F, which terminates the direct child and its descendants as long as the parent process is still alive.

On Unix, the default shell process-group cleanup is sufficient; no additional termination logic is applied.