# OAK Apps Overview

`OAK Apps` let you develop, containerize, deploy and manage containerized vision apps across Luxonis OAK devices, from single
units to fleets.

They run on the preinstalled `oak-agent` service on OAK4 devices (part of [Luxonis
OS](https://docs.luxonis.com/software-v3/sw-stack/luxonis-os.md)), so you can start deploying right away.

## What are OAK Apps?

OAK Apps are containerized computer vision applications built on the DepthAI framework that run directly on OAK devices. They
provide:

 * Consistent development environment - Build once, deploy anywhere
 * Simplified deployment - Package everything your app needs
 * Fleet management - Deploy to multiple devices simultaneously
 * Integration with Luxonis Hub - Monitor and manage devices remotely

It's important to mention that once the app is built (ie. `.oakapp` file is generated) you can move and install it to other
devices as well without needing to rebuild or require an internet connection.

### Default Application Demo

See a prebuilt Default Application to preview what a finished OAK App can look like.

[View on GitHub](https://github.com/luxonis/oak-examples/tree/main/apps/default-app)

## Creating Your OAK App

#### Project Structure

A basic OAK App project structure:

```text
my-oak-app/
├── .oakappignore      # (Optional) Files to ignore when building the app on the device
├── main.py            # Your primary application code
├── requirements.txt   # Python dependencies
└── oakapp.toml        # App configuration
```

The `oakapp.toml` file is required and contains app metadata and build instructions.

#### App Development

Creating an OAK App starts with the DepthAI API, which is the core framework powering all OAK device capabilities:

```bash
# Install DepthAI SDK
pip install depthai --force-reinstall

# Create your application using DepthAI's Python API
# - Access camera streams
# - Run neural inference
# - Process depth data
# - Leverage edge processing capabilities
```

## Deploying with oakctl

`oakctl` is a command-line tool that allows you to interact with your OAK4 cameras. It can be used to create, deploy, and manage
apps on devices that are running the `oak-agent` service.

#### Linux/MacOS

On 64bit system, run:

```bash
bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"
```

#### Windows

Download and install using the [Windows Installer](https://oakctl-releases.luxonis.com/data/latest/windows_x86_64/oakctl.msi).

### OS Compatibility Chart

| RVC4 OS version | oakctl version | Command |
| --- | --- | --- |
| OS 1.14.1+ | 0.11.0+ | `oakctl self-update` (current stable) |
| OS 1.11 | 0.9.0 | `oakctl self-update -v 0.9.0` |
| OS 1.8 | 0.4.2 | `oakctl self-update -v 0.4.2` |
| OS 1.6 | 0.2.11 | `oakctl self-update -v 0.2.11` |

### Building and Running Apps

Building and running OAK Apps is straightforward with oakctl:

```bash
# Run an app directly from source
oakctl app run ./my-oak-app

# Build the app into a distributable package
oakctl app build ./my-oak-app

# Install a built app
oakctl app install my-oak-app.oakapp
```

### App Management

You can manage apps with the following commands:

```bash
# List installed apps
oakctl app list

# Start an app
oakctl app start <container-id>

# View app logs
oakctl app logs <container-id>

# Stop an app
oakctl app stop <container-id>

# Enable auto-start
oakctl app enable <container-id>
```

## Device Management

```bash
# List connected devices
oakctl list

# Connect to a specific device
oakctl connect <device-ip>
```

## The oakapp.toml Configuration

The `oakapp.toml` file defines your app's build and runtime configuration:

```toml
# (Required) App Identifier
identifier = "com.luxonis.python_demo"
# (Required) App Entrypoint
entrypoint = ["bash", "-c", "python3 /app/main.py"]

# (Optional) Prepare container commands
# Here is the place where you can install all the dependencies that are needed at run-time
prepare_container = [
    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
    { type = "RUN", command = "apt-get update" },
    { type = "RUN", command = "apt-get install -y python3-pip" },
    { type = "RUN", command = "pip3 install -r /app/requirements.txt --break-system-packages" },
]

# (Optional) Prepare build dependencies
# Here is the place where you can install all the dependencies that are needed at build-time
prepare_build_container = [
    # Example: npm, gcc, ...
]

# (Optional) Additional commands after all the app files are copied to the container
build_steps = []
```

See [full reference](https://docs.luxonis.com/software-v3/oak-apps/configuration.md) for all available configuration options.