# 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.