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

Problems updating on Windows

If you have problems updating the oakctl version on Windows, download the installer from here.

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

By default, oakctl app run uses oakapp.toml from the provided app directory. Use --oakapp-file to select an alternative config file (for example oakapp.dev.toml or oakapp.prod.toml), as long as that file is inside the same app directory tree.

Optional flags:

Flag	Description
`-b, --detach`	Run the app in detached mode. You can stop it with `oakctl app stop <APP_ID>`.
`-d, --device [<DEVICE>]`	Specify device using IP, `IP:PORT`, index, or Serial Number from `oakctl list`.
`-i, --invalidate`	Invalidate cache and force rebuild.
`-e, --env <KEY=VALUE>`	Export runtime environment variable to the app (can be provided multiple times).
`--env-file <FILE>`	Export runtime environment variables from a `.env` file.
`--oakapp-file [<PATH>]`	Use an alternative `oakapp.toml` file (for example dev/prod variants) from inside the provided app directory tree.
`--preserve-line-endings`	Disable automatic CRLF to LF conversion before uploading files to device.

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. Use oakctl app list --long to always show full App IDs. App control commands accept both full App IDs and unique prefixes.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!

You can also use a unique App ID prefix:

Command Line

1$ oakctl app start 612a745c

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 <app-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 <app-id> -n 10

If you only want historical logs without attaching to live output, use:

Command Line

1oakctl app logs <app-id> --no-follow

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 <app-id>

You can also disable the app with the disable command:

Command Line

1oakctl app disable <app-id>

To interactively attach to the already running App on the device use the exec command:

Command Line

1oakctl app exec <app-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.

Note

Be careful when modifying files or saving data inside the container, as changes can be lost when the container is stopped or removed.

Better approach is to mount a persistent folder from the host device into the container using mounts (see oakapp.toml configuration).

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

By default, oakctl app build uses oakapp.toml from the provided app directory. Use --oakapp-file to select an alternative config file (for example oakapp.dev.toml or oakapp.prod.toml), as long as that file is inside the same app directory tree.Optional flags:

-d, --device [<DEVICE>] - specify device using IP, IP:PORT, index, or Serial Number from oakctl list
-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-description - 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
-o, --output [<PATH>] - path to the directory where the built *.oakapp file should be downloaded
--oakapp-file [<PATH>] - use an alternative oakapp.toml file from inside the provided app directory tree
--preserve-line-endings - disable automatic CRLF to LF conversion before uploading files to device

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

To change the active team, run oakctl hub login again and select the team in the web login flow. oakctl hub switch-team is an alias to oakctl hub login.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.

Release Notes for oakctl and oak-agent

agent v0.18.3, oakctl v0.18.2 (February 17, 2026)

Added

Image download progress reporting during oakctl app build and oakctl app run commands.
GPU support for self-hosted agent, which allows oak apps to use the host's Nvidia GPU if enabled.
oakctl app [build|run] --oakapp-file [PATH] arg to specify a custom path to the oakapp.toml file.
oakctl app logs --no-follow arg to avoid attaching to the log stream.
Remote command execution from Luxonis Hub.
Replaced --*-b64 arguments of oakctl setup with a new subcommand oakctl setup-b64.
Rejection of relative paths in oakapp.toml mount fields: required_mounts, required_devices, optional_mounts, optional_devices, additional_mounts.
oakctl device update support for self-hosted oak-agent.

Fixed

Failed to mount overlayfs error on oakctl app build when trying to use a base image with many layers (around 30).
oakctl adb on jetson.
Added installation of QDL udev rules to oakctl self-update.
- Fixes some instances of qdl: Failed to open device during oakctl device flash.
/etc/resolv.conf missing in container on second app run after editing oakapp.toml.

agent v0.17.4, oakctl v0.17.4 (January 15, 2026)

Added

oakctl app build --output [PATH] argument to indicate where to download the *.oakapp file after building it.
Base64-encoded arguments of oakctl setup command to ensure cross-OS-compatible escaping of special characters for the Hub-generated setup command.
Automated check for new oakctl versions once per day.
oakctl app prune-storage command to remove unnecessary app files.
oakctl app list --long flag to show full App ID.
oak-agent tests WebRTC connection.
oakctl device info and oakctl list show adoption status.
Welcome ACK factory reset support.
oakctl app install updates an existing app by default.
- Can be modified with --force-new flag to install as a new app.
- Can be modified with --update flag to update a specific existing app.
oakctl app install --env / --env-file to set environment variables during app installation.
Multiplatform self-hosted Docker image.

Changed

oakctl app list now shows App IDs truncated to 3 characters by default; truncation increases automatically when there are collisions.
oak-agent saves new app build metadata.
Self-hosted WebRTC terminal opens host shell instead of container shell.
oakctl app <ACTION> <app-id> commands now accept both full and truncated App IDs.

Fixed

Fixed an issue where OTA update status deserialization failed if multiple messages were received in a single read.
oakctl on Windows converts CRLF to LF automatically.
Self-hosted oak-agent/oakctl fixes:
- fixed oakctl device info --check_internet
- fixed oakctl device reboot
- fixed oakctl setup command (failed on some devices like RPi)
- adb binary for ARM devices was missing (mistakenly included x86 binary instead)
Fixed app publish upload with OAKCTL_HUB_TOKEN.
oakctl builds for macOS ARM and Windows were not signed.
Fixed build cache invalidation for oak-agent.
Fixed an issue where oakctl did not save and/or read sn-data.json correctly.

Deprecated

OAKCTL_HUB_LOGIN_TOKEN env renamed to OAKCTL_HUB_TOKEN.
oakctl hub switch-team is now an alias to oakctl hub login (team is selected in web login flow).
--enabled flag renamed from -e to -E.

oakctl v0.16.5 (December 15, 2025)

Added

New flag --yes for non-interactive oakctl device update.
New flag --check_internet for oakctl device update to check internet connectivity before updating.
oakctl viewer command to open Viewer is enabled.
New flag --no-download for oakctl app build to skip downloading built *.oakapp file to host; useful for tests.
New flags --enable and --disable-others for oakctl app start.

Changed

oakctl hub login now uses web-based authentication flow.
Minor improvements for integration into Viewer.

ON THIS PAGE

oakctl tool

Installation

Linux/MacOS

Windows

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

Release Notes for oakctl and oak-agent

agent v0.18.3, oakctl v0.18.2 (February 17, 2026)

Added

Fixed

agent v0.17.4, oakctl v0.17.4 (January 15, 2026)

Added

Changed

Fixed

Deprecated

oakctl v0.16.5 (December 15, 2025)

Added

Changed