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

On 64bit system, run:

Command Line

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

Windows

Download and install using the Windows Installer.

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

Environment variables

You can pass environment variables to the app using -e, --env flag or --env-file flag. These variables will be available in the app's runtime environment and can be used to configure the app without changing the code.

Command Line

1oakctl app run ./app/path --env KEY1=VALUE1 --env KEY2=VALUE2

Some apps may require specific environment variables to be set for them at build time (for example API keys, model download links, etc.). In that case, you can set those variables in the oakapp.toml file using build_env field or pass them during build with --build-arg flag:

Command Line

1oakctl app build ./app/path --build-arg KEY1=VALUE1 --build-arg KEY2=VALUE

Some environment variables are set in each app by default:

Variable	Description
`OAKAGENT_APP_ID`	Unique app ID.
`OAKAGENT_CONTAINER_ID`	Container ID (may differ from App ID if the app was updated).
`OAKAGENT_APP_IDENTIFIER`	App identifier from `oakapp.toml`.
`OAKAGENT_APP_VERSION`	App version from `oakapp.toml`.
`DEPTHAI_ZOO_MODELS_PATH`	Path to DepthAI Zoo models directory; set based on `depthai_models` field in `oakapp.toml`; prefer to not modify manually.
`DEPTHAI_ZOO_CACHE_PATH`	Path to DepthAI Zoo cache directory; used for caching downloaded models; prefer to not modify manually.
`DEPTHAI_ZOO_INTERNET_CHECK`	Enable internet connectivity check for model downloads; set based on `depthai_models` field in `oakapp.toml`; prefer to not modify manually.
`DEPTHAI_DEVICE_NAME_LIST`	Set to `127.0.0.1` on all RVC4 devices to make sure that standalone apps use only the device they are running on, even if there are multiple devices on the same network.
`OAKAPP_STATIC_FRONTEND_PATH`	Path to static frontend files for the app.
`OAKAPP_STATIC_FRONTEND_PORT`	Port for serving static frontend files. It is set from range 9000-9128 to avoid conflicts with the ports used by the agent or other apps.
`OAKAGENT_STORAGE_APP`	App-specific persistent storage path.
`OAKAGENT_STORAGE_SHARED`	Shared storage path accessible across apps with the same identifier.
`OAKAGENT_STORAGE_GLOBAL`	Global storage path on the device.

Persistent Storage

Persistent storage paths are used to store data that should persist across app restarts and updates. These paths are mounted into the app's container. You can choose the target directory name for the storage in the container with oakapp.toml configuration (storage_dir_name).

OAKAGENT_STORAGE_APP is a storage path that is unique to each app and is not shared with other apps. It is useful for storing app-specific data that should not be accessible by other apps.
OAKAGENT_STORAGE_SHARED is a storage path that is shared between all apps with the same identifier. It is useful for storing data that should be accessible by different installations of the same app.
OAKAGENT_STORAGE_GLOBAL is a global storage path that is not tied to any specific app. It is useful for storing data that should be accessible regardless of which apps are installed or running.

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| * | f8da5  | com.luxonis.default:1.3.8 | running | 10.0.1.24:9000    |
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.

Note

App IDs are truncated in the list for better readability. If there are multiple apps with the same prefix, the truncation length increases until all app IDs are unique. You can also use the --long flag to show full app IDs in the list.

All app control commands accept both full and truncated App IDs as long as they are unique.

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) or persistent storage that is managed by the OAK agent (see OAKAGENT_STORAGE_APP, OAKAGENT_STORAGE_SHARED, OAKAGENT_STORAGE_GLOBAL 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

Update an app

App updates can be performed using the oakctl app install command. By default, oakctl app install attempts to update an existing app with the same identifier. Use the --force-new flag to install a new instance instead of updating (this is useful for self-hosted oak-agent; Luxonis OS does not allow multiple DepthAI apps at the same time).If multiple apps share the same identifier, specify which one to update using the --update <APP_ID> flag.The update process follows these steps:

The new app version is downloaded from the Hub, URL, or local *.oakapp file (depending on the source: -i, -u, or file path). The current version remains running during this step.
Once the new version is downloaded and validated, the current version stops and the new version starts. Any previous rollback version is then removed.

For more control, you can perform updates manually:

Stage the new version: oakctl app install --manual-update downloads and prepares the new version without stopping the current one. Verify readiness with oakctl app list.
Commit the update: oakctl app update <APP_ID> --commit stops the current version and starts the new one.
Rollback if needed: oakctl app update <APP_ID> --rollback reverts to the previous version if issues occur.
Finalize when ready: oakctl app update <APP_ID> --finalize removes the old version kept for rollback once you confirm the new version is stable.

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

Use --check_internet flag to check internet connectivity as well.

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]

Update command works only if the device is connected to the internet.

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.6, oakctl v0.18.6 (April 8, 2026)

Added

oakctl app install now deletes unnecessary files after installation to save storage space.
oakctl app prune-storage now removes installation and download files too.
oakctl app delete now also deletes malformed apps.
oakctl device info now shows:
- date
- network information
- HTTP API port for downloading built apps
oakctl app run no longer rebuilds the whole app if a command fails during build steps; it keeps successfully built layers instead.
New oakapp.toml definition:
- Added shell field to specify the default shell for RUN commands, build_steps, and entrypoint (default: ["/bin/sh", "-c"]).
- Commands can now be written in shell form (string) or exec form (array of strings).
- Removed shlex-based parsing because it did not support constructs like redirection and pipes.
- Added optional arg section for build-time environment variables and --build-arg flag for oakctl app build and oakctl app run.
- Added optional additional_build_mounts section for mounts used only during the build stage.
All Hub service endpoints can now be configured by API.
- Use OAKCTL_HUB_API_URL in oakctl.
- Use api= in setup-utility config for oak-agent.

Changed

Renamed the env variable that selects the Hub services environment in oakctl from ENV to OAKCTL_ENV.

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

Environment variables

App Management

List installed apps

App control flow

Install an app

Update 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.6, oakctl v0.18.6 (April 8, 2026)

Added

Changed

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