---
title: "wendy run"
description: "Build and run application on a WendyOS device"
---

## Syntax

```sh
wendy run [flags]
```

## Examples

```sh
wendy run
wendy run --watch
wendy run --device my-robot
wendy run --detach
```

## Arguments

No positional arguments are declared in the command synopsis.

## Flags

Flags below include inherited options. Types and defaults come from the CLI source. An empty default means no value is configured.

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--build-host` | string | (empty) | Build on another WendyOS device; omit the device to open a picker, or use --build-host=DEVICE Value when used without an argument: `" "`. |
| `--build-type` | string | (empty) | Build type to use when Dockerfile/Containerfile is present alongside Package.swift or Python project markers: docker, swift, or python |
| `--builder` | string | (empty) | Image builder to force for Dockerfile/Containerfile builds: docker, apple-container, or buildkit |
| `--chunking` | string | `auto` | Content-defined chunking (CBC) deploy path: auto (try chunk-diff, fall back to registry push), force (chunk-diff only, no fallback), or off (registry push only) |
| `--debounce` | int | `400` | Watch mode (--watch): quiet period in milliseconds after the last change before redeploying |
| `--debug` | bool | `false` | Enable debug logging |
| `--deploy` | bool | `false` | Create container but do not start it |
| `--detach` | bool | `false` | Start container and return without streaming logs, waiting for readiness, or opening the app URL |
| `--device` | string | (empty) | Target device hostname; `wendy run` accepts a comma-separated list to deploy one build to several devices (needs a remote build host and --detach). Defaults to $WENDY_DEVICE, then the saved default device |
| `--dockerfile` | string | (empty) | Build file to build from: a Dockerfile, Containerfile, or Stagefile (e.g. Dockerfile.prod, Containerfile, prod.stagefile.yaml); shows a selection menu when multiple build files exist |
| `--env` | stringArray | `[]` | Set an environment variable in the container as KEY=VALUE; repeatable, and overrides wendy.json env of the same key |
| `--gpu-arch` | string | (empty) | GPU architecture a Stagefile cuda: stage targets (sm_87); read from the device when one is selected |
| `--hil` | string | (empty) | Run hardware in the loop; omit the device to open a cloud picker, or use --hil=DEVICE Value when used without an argument: `" "`. |
| `--json` | bool | `false` | Output in JSON format |
| `--keep-going` | bool | `false` | Multi-service: deploy services that build successfully instead of aborting the whole group on the first build/push failure |
| `--max-concurrency` | int | `0` | Multi-service/Compose: max service images to build+push at once (0 = default limit of 4) |
| `--no-restart` | bool | `false` | Do not restart on exit |
| `--prefix` | string | (empty) | Project directory to run from instead of the current working directory |
| `--product` | string | (empty) | Swift Package Manager product to build and run |
| `--restart-on-failure` | bool | `false` | Restart on failure |
| `--restart-unless-stopped` | bool | `false` | Restart unless manually stopped |
| `--service` | string | (empty) | Build and run only the named service and its dependencies (multi-service projects) |
| `--skip-cloud-registration` | bool | `false` | Deploy without registering apps in Cloud (offline use) |
| `--stagefile-backend` | string | (empty) | Stagefile compiler backend: dockerfile (default) or llb |
| `--user-args` | stringSlice | `[]` | Extra arguments to pass to the container |
| `--verbose` | bool | `false` | Watch mode (--watch): always show build output (default: hidden unless the build fails) |
| `--watch` | bool | `false` | Watch the project directory and redeploy on every change, streaming logs between deploys (same as 'wendy watch') |
| `--yes` / `-y` | bool | `false` | Automatically accept all interactive prompts |

## Output

An attached run streams build progress and app logs. When readiness succeeds and a URL can be inferred, it prints a line such as:

```text
App reachable at http://127.0.0.1:3000
```

The address depends on the target. `--detach` skips log streaming, host readiness checks, and browser opening. Ordinary single-device agent deployments report configured HTTP endpoints. With `--json --detach`, one result goes to stdout and progress goes to stderr; `readiness: "not_checked"` leaves application health unverified. See Details for the result shape and supported modes.

## JSON output

The global `--json` option requests machine-readable output. The CLI also selects JSON mode when no interactive terminal is attached. Support and payloads are command-specific; this flag does not guarantee a single JSON document for commands that stream logs or invoke build tools. Consult Details before parsing command output.

## Exit codes

The CLI entry point returns `0` on success and for its user-cancelled or default-cleared results. Other returned errors exit with `1` and print a diagnostic to stderr. Some operations may terminate through subprocess or signal handling; do not infer application health from the CLI exit code alone.

## Common errors

Check argument values and flag combinations against the synopsis above. For discovery, build, port, and readiness failures, see [deployment troubleshooting](../../../errors/). Command-specific constraints are in Details.

## See also

- [wendy](../../../reference/cli/)
- [CLI conventions and configuration](../../../reference/)

## Details

Reads wendy.json from the current directory or --prefix directory, builds a container image, and deploys it to the target device.

[Command behavior and detailed examples](../../../advanced/clients/wendy-cli/commands/run/)