CloudSoftwareHardware
Software Stack
DepthAI
OAK Apps
AI Models
Troubleshooting

ON THIS PAGE

  • Installation
  • Update
  • Usage
  • Connect to a device
  • Find devices
  • App Development
  • Optional flags:
  • Example apps
  • App Management
  • List installed apps
  • App control flow
  • Install an app
  • Build And Publish App
  • Hub connection
  • Device Management
  • Device Info
  • Device Update
  • Device Reboot
  • Device Unlock
  • Device Flash
  • oak-agent
  • Containers

oakctl tool

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 and devices that are running the oak-agent service and are on the local network.Note that oak-agent is pre-installed on OAK4 devices (it's baked into the Luxonis OS), so you can start using oakctl right away.

Installation

Linux/MacOS
Windows

Linux/MacOS

On 64bit system, run:
Command Line
1bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"

Update

You can update the oakctl tool later like this:
Command Line
1oakctl self-update

Usage

Connect to a device

If only one device is available within the network, you can connect to it with the following command:
Command Line
1oakctl connect
If you have multiple devices or the device is not in the same network as your PC, you can specify the device's IPv4 address to connect to it:
Command Line
1oakctl connect 10.0.1.24
Optionally, you can store your device's password using --with-password flag. This will prevent you from entering the password every time the session expires.

Find devices

oakctl allows you to interact with your devices that have oak-agent installed. You can list all available devices (found on your network) with the following command:
Command Line
1oakctl list
2+---+---------------+---------------+------------+----------------+---------------+-------+
3| # | Serial Number | Device        | Connection | OS             | Agent Version | Setup |
4+=========================================================================================+
5| 1 | 1623452492    | Luxonis, Inc. | 10.0.1.24  | OS RVC4 1.18.0 | 0.13.7        | OK    |
6|   |               |  OAK4-D R7    |            |                |               |       |
7+---+---------------+---------------+------------+----------------+---------------+-------+

App Development

You can run the app with the command below:
Command Line
1oakctl app run /app/path/to/source
The path above needs to contain the oakapp.toml file.

Optional flags:

FlagDescription
-d, --device <DEVICE_IP>Specify the device to run the app on. By default, it will run on the first device from the list
-b, --detachRun the app in the background (detached mode). You can stop the app with oakctl app stop <CONTAINER_ID>

Example apps

We prepared example apps that you can run on your OAK4 device. Below we'll use Human pose detection example, which also contains the oakapp.toml:
Command Line
1git clone https://github.com/luxonis/oak-examples.git
2cd oak-examples
3# Run an app
4oakctl app run ./neural-networks/pose-estimation/human-pose # or some other example

App Management

You can install multiple apps on the device. If you are developing an app, you can share compiled apps with others within the team.Be sure you run only one DepthAI app at a time.Most of the app management commands have optional flags -d, --device <DEVICE> to specify the device to run the command on (IP address or index from the oakctl list).

List installed apps

If you setup the device and adopted in the Hub, you probably have one app installed (com.luxonis.default).
Command Line
1$ oakctl app list
2+---+--------------------------------------+---------------------------+---------+--------------+
3| E | App Id                               | Identifier                | Status  | Frontend URL |
4+===============================================================================================+
5| * | f8da56a4-b602-45ec-8fda-7588bf7c473a | com.luxonis.default:1.3.8 | running | 10.0.1.24    |
6+---+--------------------------------------+---------------------------+---------+--------------+
First column (E) has asterisk if the app is enabled.Any app can be in one of the following states: installing, building, ready, starting, running, stopping, stopped, deleting, deleted, unknown.Ready means the app is installed and ready to run, but it was not started since the agent was started, while stopped means the app is installed but not running, it was stopped by the user.

App control flow

The basic commands to control the app are start, stop, and delete. First, let's start the app:
Command Line
1$ oakctl app start 612a745c-8d68-4264-a3d6-d06d14275ef5
2Starting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been started!
Now, let's read app logs - this command will read the app's logs and print them to the console as they are received:
Command Line
1$ oakctl app logs <container-id>
2Reading logs ...
3  Press Ctrl+C to stop reading logs.
4  App output:
5    [2025-02-12T14:37:54Z] Hello cli 1 / Wed Feb 12 14:37:54 UTC 2025
Optionally, you can specify the number of previous lines to read with the -n flag:
Command Line
1oakctl app logs <container-id> -n 10
Now you can stop the app:
Command Line
1$ oakctl app stop 612a745c-8d68-4264-a3d6-d06d14275ef5
2Stopping app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been stopped!
And here is how you can delete the app:
Command Line
1$ oakctl app delete 612a745c-8d68-4264-a3d6-d06d14275ef5
2Deleting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3  App has been deleted!
Any app can be enabled or disabled. If the app is enabled, it will start automatically when the device is booted.
Command Line
1oakctl app enable <container-id>
You can also disable the app with the disable command:
Command Line
1oakctl app disable <container-id>
To interactively attach to the already running App on the device use the exec command:
Command Line
1oakctl app exec <container-id> -i /bin/bash
This will open an interactive bash shell inside the app's container, allowing you to inspect files, processes, and environment variables.

Install an app

App can be found in Hub in section OAK4 Apps. There are apps that are shared with the team and apps that are shared with your team or public apps. By default, a newly installed app stops all others and is enabled and running. You can modify this behavior by using --enable=false or --keep-others flags.App installation is done by following command:
Command Line
1$ oakctl app install com-example-emotion_recognition_1-0-1.oakapp
2Sending data to agent ...
3  Data sent successfully!
4
5✔ Oakapp package built successfully.                                                                                                         
6Installed app has ID: ddb8a884-d9e1-4779-a88b-c30d5d1e265f
7
8Start the app:  oakctl app start ddb8a884-d9e1-4779-a88b-c30d5d1e265f
App can be installed from an *.oakapp file, from Hub (by identifier) or from URL.If you want to install app from Hub, do this:
Command Line
1# Install app by identifier
2oakctl app install -i com.example.app
There is also an option to install app by URL if the app is somewhere on the internet:
Command Line
1# Install app by URL
2oakctl app install -u https://example.com/app.oakapp

Build And Publish App

You can build your own app. The process will produce *.oakapp file that can be installed on other devices:
Command Line
1oakctl app build ./folder/app/src
The specified path needs to contain the oakapp.toml file. There are two optional flags:
  • -k, --keep - keep the container after the build (useful if you want to oakctl app start it right after the build)
  • -p, --publish - publish the app to the Hub after the build (the app will show up in the Hub's OAK4 Apps).
  • -O, --optimized - build the app in optimized mode (smaller size, longer build time)
  • -U, --update-descriptioon - update the app description on the Hub if the app is published
  • -N, --no-download - do not download the oakapp file to host after build
If you publish the app, you need to specify the app's identifier and unique version in oakapp.toml file.

Hub connection

For some operations, you need to connect the device to the Hub. You can do this with the following command:
Command Line
1oakctl hub login
After you log in, you can check the status of the connection with the following command:
Command Line
1oakctl hub status
After you log in, you can change active team anytime with the following command:
Command Line
1oakctl hub switch-team
Logout using:
Command Line
1oakctl hub logout
Once you're logged in, you can publish built *.oakapp packages:
Command Line
1oakctl hub publish <oakapp-file>
You can also run local scripts that require the Hub token for model downloads, etc.:
Command Line
1oakctl hub run-script <script-file>

Device Management

Device Info

Device info command will show you the device's information, such as OS version, agent version, architecture, serial number, and model.
Command Line
1$ oakctl device info
2Device Info:
3  OS:                   Luxonis OS RVC4 1.4.0
4  Agent Version:        2.0.11 (rvc4)
5  Architecture:         linux/arm64
6  Serial Number:        2713799968
7  Model:                Luxonis, Inc. KalamaP OAK4-D R1

Device Update

Device can be updated with the following command - possible values for CHANNEL are stable and beta:
Command Line
1oakctl device update --channel=[CHANNEL]
This command will check the latest available version and update the device if the version is different.You can select the specific version to update to using --select flag:
Command Line
1oakctl device update --select --channel=[CHANNEL]

Device Reboot

You can reboot the device using oakctl:
Command Line
1oakctl device reboot
This command will reboot the device and wait for it to come back online.

Device Unlock

New devices have disabled SSH access by default. You can enable it using the following command:
Command Line
1oakctl device unlock
This command will prompt you to set a password.

Device Flash

You can flash the device (USB only) with a new Luxonis OS image using the following command:
Command Line
1oakctl device flash [<path-to-tar.xz>]
Path to the *.tar.xz image is optional; if not specified, the latest stable image will be downloaded and flashed. For detailed flashing and OS update instructions see updating OS page.

oak-agent

oak-agent is a service that runs on the OAK4 device and manages the containers. It's responsible:
  • Managing apps, running containers
  • Communicating with the oakctl tool
  • Communicating with the Hub (cloud platform)

Containers

oak-agent uses runc as a lightweight container runtime, which is also what Docker/Podman uses. We opted-in for runc because it's lightweight and gives us full control over the container lifecycle.