App Entitlements

Understanding Entitlements

Entitlements are permissions that grant your application access to hardware resources and system capabilities on your WendyOS device. By default, applications run in isolated containers with minimal privileges. Entitlements allow you to selectively enable access to features like networking, GPU, video capture, audio, and Bluetooth.

Why Entitlements?

WendyOS uses a security-first approach where applications are sandboxed by default. This means:

• Applications cannot access the network unless explicitly granted
• Hardware devices (cameras, microphones, GPUs) are not accessible by default
• Bluetooth and other system interfaces require explicit permission

Entitlements provide a declarative way to request these permissions, making it clear what resources your application needs.

The wendy.json File

Entitlements are configured in your project's wendy.json file. This file defines your application's identity and the permissions it requires.

Basic Structure

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

Available Entitlements

Network Entitlement

The network entitlement controls how your application accesses the network.

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

GPU Entitlement

The GPU entitlement enables access to NVIDIA GPU hardware on Jetson devices. This is essential for machine learning inference, computer vision, and GPU-accelerated computing.

{
  "type": "gpu"
}

When enabled, this entitlement:

• Adds your application to the video group for GPU device access
• Injects NVIDIA Container Device Interface (CDI) specifications
• Sets up environment variables for CUDA and GPU libraries

Video Entitlement

The video entitlement provides access to video capture devices like USB cameras or CSI cameras.

{
  "type": "video"
}

When enabled, this entitlement:

• Mounts /dev/video0 into your container
• Configures device permissions for video capture
• Enables access to V4L2 (Video4Linux2) interfaces

Audio Entitlement

The audio entitlement enables access to audio input and output devices.

{
  "type": "audio"
}

When enabled, this entitlement:

• Mounts the /dev/snd directory into your container
• Configures ALSA device permissions
• Enables recording and playback capabilities

Bluetooth Entitlement

The Bluetooth entitlement allows your application to communicate with Bluetooth devices.

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

When using kernel mode, this entitlement:

• Adds network administration capabilities (CAP_NET_ADMIN, CAP_NET_RAW)
• Configures seccomp filters for Bluetooth socket operations
• Enables direct HCI socket communication with the Bluetooth controller

When using bluez mode, this entitlement:

• Provides access to the BlueZ D-Bus interface
• Allows interaction with paired devices and Bluetooth profiles
• Enables use of standard Bluetooth libraries that depend on BlueZ

Common Configurations

Web Server with Camera

For applications that serve video streams over HTTP:

{
  "appId": "com.example.video-streamer",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "video" }
  ]
}

Machine Learning Inference Server

For AI/ML applications that expose an API:

{
  "appId": "com.example.ml-server",
  "version": "1.0.0",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "gpu" }
  ]
}

Computer Vision with GPU

For applications that process video using GPU acceleration:

{
  "appId": "com.example.vision-app",
  "version": "1.0.0",
  "entitlements": [
    { "type": "gpu" },
    { "type": "video" }
  ]
}

Voice Assistant

For applications that use audio input/output and Bluetooth:

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

Minimal Hello World

For simple applications that don't need any hardware access:

{
  "appId": "com.example.hello-world",
  "version": "1.0.0",
  "entitlements": []
}

Managing Entitlements with the CLI

You can manage entitlements using the Wendy CLI without manually editing JSON files.

Add an Entitlement

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 an Entitlement

wendy project entitlements remove network
wendy project entitlements remove gpu

List Current Entitlements

wendy project entitlements list

Best Practices

1. Request only what you need: Only add entitlements that your application actually requires. This follows the principle of least privilege.

2. Document your entitlements: Add comments in your README explaining why each entitlement is needed.

3. Test without entitlements first: Start with an empty entitlements array and add permissions as needed when you encounter access errors.

4. Use host networking for servers: Any application that accepts incoming connections (HTTP servers, WebSocket servers, etc.) needs the network entitlement with mode: host.

5. Combine entitlements thoughtfully: Some use cases require multiple entitlements. For example, a video streaming server needs both network and video entitlements.

Troubleshooting

Application can't access the network

Ensure you have the network entitlement with host mode:

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

GPU not detected in container

Verify the GPU entitlement is present and you're running on a Jetson device:

{ "type": "gpu" }

Camera not found

Add the video entitlement and verify your camera is connected:

{ "type": "video" }

Check that your camera appears as /dev/video0 on the host device.

Permission denied for audio devices

Add the audio entitlement:

{ "type": "audio" }

Bluetooth operations failing

Ensure you have the Bluetooth entitlement with the appropriate mode:

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

Or if using BlueZ libraries:

{ "type": "bluetooth", "mode": "bluez" }