wendy

Original source / Raw SKILL.md

---
name: wendy
description: 'Expert guidance on building and deploying apps to WendyOS edge devices. Use when developers mention: (1) Wendy or WendyOS, (2) wendy CLI commands, (3) wendy.json or entitlements, (4) deploying apps to edge devices, (5) remote debugging Swift on ARM64, (6) NVIDIA Jetson or Raspberry Pi apps, (7) cross-compiling Swift for ARM64.'
references:
  - wendy.json.md
---

# WendyOS

WendyOS is an Embedded Linux operating system for edge computing. It supports:
- NVIDIA Jetson devices (production with OTA updates)
- Raspberry Pi 4/5 (edge devices)
- ARM64 VMs (development)

## Learning About Wendy

Before helping with Wendy commands, run this to learn all available commands:

```bash
wendy --experimental-dump-help
```

This outputs a JSON structure with all commands, flags, and documentation.

Whenever you invoke a wendy command, use the JSON structure options to provide structured JSON output. This will also prevent interactive dialogs and errors. Use `--json` or `-j` to provide JSON output.

## Common Tasks

- Run an app: `wendy run`
- Discover devices: `wendy discover`
- Update agent: `wendy device update`
- Configure WiFi: `wendy device wifi connect`
- Install WendyOS on an external drive: `wendy os install`
- Set a device as default using `wendy device set-default`

## Setup and Configuration

Wendy CLI connects to a device over gRPC (TCP) port 50051. If Wendy CLI is not installed yet, you can use `brew install wendy` to install it.

Devices are discovered over USB or LAN. If a device is not found, ask the user to check the connection or to connect it over USB.
If a device is not yet installed, use `wendy os install` to install the OS to an external drive. For NVIDIA Jetson devices, the OS is commonly installed to NVMe.

## Development

WendyOS is a Linux-based containerized operating system. It uses Linux containers to run your apps.

WendyOS uses Swift.org as its flagship language. This uses Swift Package Manager and the Swift Container Plugin to build and run your app. Wendy CLI will cross compile Swift for you.

Other programming languages are supported, but require the use of a Dockerfile to build your app.

### Entitlements

WendyOS uses an entitlement system, managed through `wendy.json`, to manage permissions for your app. This reflects how your container will be set up on the device.

See `references/wendy.json.md` for detailed entitlement configuration.

### Quick Start

1. Create a new Swift project or navigate to an existing one
2. Initialize wendy.json: `wendy project init`
3. Add required entitlements (e.g., for a web server): `wendy project entitlements add network --mode host`
4. Run on device: `wendy run`

### Common Entitlements

| Entitlement | Use Case |
|-------------|----------|
| `network` (host mode) | Web servers, HTTP APIs, incoming connections |
| `gpu` | ML inference, computer vision (Jetson only) |
| `video` | Camera access, video capture |
| `audio` | Microphone, speakers |
| `bluetooth` | BLE devices, Bluetooth communication |

## Remote Debugging

WendyOS provides built-in support for remote debugging Swift apps. Use `wendy run --debug` to include and launch a debugging session.
This exposes a GDB server on port 4242.

### Connecting from VS Code

1. Run `wendy run --debug`
2. In VS Code, use the CodeLLDB extension
3. Connect to `<device-ip>:4242`

## Observability

WendyOS runs a local OpenTelemetry collector on each device. Apps should report telemetry (logs, metrics, traces) to this local collector.

### Configuration

Use HTTP protocol (not gRPC) for OTel exports:

```swift
import OTel

var config = OTel.Configuration.default
config.traces.otlpExporter.protocol = .httpProtobuf
config.traces.otlpExporter.endpoint = "http://localhost:4318"
config.metrics.otlpExporter.protocol = .httpProtobuf
config.metrics.otlpExporter.endpoint = "http://localhost:4318"
config.logs.otlpExporter.protocol = .httpProtobuf
config.logs.otlpExporter.endpoint = "http://localhost:4318"

let observability = try OTel.bootstrap(configuration: config)
```

Or via environment variables:

```bash
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```

The local collector handles forwarding telemetry to your backend infrastructure.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Device not found | Check USB/LAN connection, run `wendy discover` |
| Network access denied | Add network entitlement with host mode |
| GPU not detected | Add gpu entitlement (Jetson only) |
| Camera not found | Add video entitlement, verify camera at `/dev/video0` |
| Build fails | Check Swift version compatibility, try `wendy run --verbose` |

## Reference Files

Load these files as needed for specific topics:

- **`references/wendy.json.md`** - App configuration, entitlements (network, gpu, video, audio, bluetooth), common configurations, CLI commands

## Further Reading

WendyOS documentation at https://wendy.sh/docs/


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/wendy.json.md

```markdown
# wendy.json Reference

The `wendy.json` file configures your WendyOS application's identity and entitlements (permissions).

## File Structure

```json
{
  "appId": "com.example.myapp",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" }
  ]
}
```

| Field | Description |
|-------|-------------|
| `appId` | Unique identifier (reverse domain notation recommended) |
| `version` | Application version string |
| `entitlements` | Array of entitlement objects specifying required permissions |

## Entitlements Overview

WendyOS uses a security-first approach where applications are sandboxed by default:
- No network access unless explicitly granted
- Hardware devices (cameras, microphones, GPUs) not accessible by default
- Bluetooth and other system interfaces require explicit permission

## Available Entitlements

### Network Entitlement

Controls network access for your application.

```json
{ "type": "network", "mode": "host" }
```

| Mode | Description |
|------|-------------|
| `host` | Shares host's network stack. Required for HTTP servers and services accepting incoming connections. |
| `none` | Isolated network namespace with no network access. For offline data processing tasks. |

**Important**: Web servers and applications accepting incoming connections need `"mode": "host"`.

### GPU Entitlement

Enables NVIDIA GPU access on Jetson devices for ML inference, computer vision, and GPU-accelerated computing.

```json
{ "type": "gpu" }
```

When enabled:
- Adds application to the video group for GPU device access
- Injects NVIDIA Container Device Interface (CDI) specifications
- Sets up CUDA and GPU library environment variables

**Note**: GPU entitlements are specifically for NVIDIA Jetson devices.

### Video Entitlement

Provides access to video capture devices (USB cameras, CSI cameras).

```json
{ "type": "video" }
```

When enabled:
- Mounts `/dev/video0` into container
- Configures device permissions for video capture
- Enables V4L2 (Video4Linux2) interfaces

### Audio Entitlement

Enables access to audio input and output devices.

```json
{ "type": "audio" }
```

When enabled:
- Mounts `/dev/snd` directory into container
- Configures ALSA device permissions
- Enables recording and playback capabilities

### Bluetooth Entitlement

Allows communication with Bluetooth devices.

```json
{ "type": "bluetooth", "mode": "kernel" }
```

| Mode | Description |
|------|-------------|
| `kernel` | Direct kernel-level Bluetooth via HCI sockets. For low-level control and custom protocol implementations. |
| `bluez` | Uses BlueZ daemon's D-Bus API. Recommended for standard Bluetooth profiles (A2DP, HFP, GATT). |

**kernel mode** adds:
- Network administration capabilities (`CAP_NET_ADMIN`, `CAP_NET_RAW`)
- Seccomp filters for Bluetooth socket operations
- Direct HCI socket communication

**bluez mode** provides:
- BlueZ D-Bus interface access
- Interaction with paired devices and Bluetooth profiles

## Common Configurations

### Web Server with Camera
```json
{
  "appId": "com.example.video-streamer",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "video" }
  ]
}
```

### Machine Learning Inference Server
```json
{
  "appId": "com.example.ml-server",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "gpu" }
  ]
}
```

### Computer Vision with GPU
```json
{
  "appId": "com.example.vision-app",
  "version": "1.0.0",
  "entitlements": [
    { "type": "gpu" },
    { "type": "video" }
  ]
}
```

### Voice Assistant
```json
{
  "appId": "com.example.voice-assistant",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "audio" },
    { "type": "bluetooth", "mode": "kernel" }
  ]
}
```

### Minimal (No Hardware Access)
```json
{
  "appId": "com.example.hello-world",
  "version": "1.0.0",
  "entitlements": []
}
```

## CLI Commands

### Add Entitlements
```bash
wendy project entitlements add network --mode host
wendy project entitlements add network --mode none
wendy project entitlements add gpu
wendy project entitlements add video
wendy project entitlements add audio
wendy project entitlements add bluetooth --mode kernel
wendy project entitlements add bluetooth --mode bluez
```

### Remove Entitlements
```bash
wendy project entitlements remove network
wendy project entitlements remove gpu
```

### List Entitlements
```bash
wendy project entitlements list
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Can't access network | Add `{ "type": "network", "mode": "host" }` |
| GPU not detected | Add `{ "type": "gpu" }` (Jetson devices only) |
| Camera not found | Add `{ "type": "video" }`, verify camera at `/dev/video0` |
| Audio permission denied | Add `{ "type": "audio" }` |
| Bluetooth operations failing | Add `{ "type": "bluetooth", "mode": "kernel" }` or `"mode": "bluez"` |

## Best Practices

1. **Least privilege**: Only request entitlements your app actually needs
2. **Start minimal**: Begin with empty entitlements, add as needed when encountering access errors
3. **Use host networking for servers**: Any app accepting incoming connections needs network entitlement with `mode: host`
4. **Document entitlements**: Explain in README why each entitlement is required
5. **Watch for port conflicts**: With host mode, app ports are exposed directly on device

```