OverviewHardwareSoftwareCloud
OAK Apps
DepthAI
AI
Software Stack
Troubleshooting

ON THIS PAGE

  • Configuration Fields
  • App Metadata
  • App Build and Runtime Configuration
  • App Layers
  • Mounts
  • Static frontend
  • DepthAI Models Cache
  • Environment Variables and Build Arguments

Configuration (oakapp.toml)

Within each app's directory, there must be a oakapp.toml file that contains static app's metadata and build steps. Metadata includes the app's identifier and version. Build steps are commands that are executed in the container to build or run the app. Example oakapp.toml file:
Toml
1# (Required) App Identifier
2identifier = "com.luxonis.python_demo"
3# (Required) App Entrypoint
4entrypoint = ["bash", "-c", "python3 /app/main.py"]
5
6# (Optional) Prepare container commands
7# Here is the place where you can install all the dependencies that are needed at run-time
8prepare_container = [
9    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
10    { type = "RUN", command = "apt-get update" },
11    { type = "RUN", command = "apt-get install -y python3-pip" },
12    { type = "RUN", command = "pip3 install -r /app/requirements.txt --break-system-packages" },
13]
14
15# (Optional) Prepare build dependencies
16# Here is the place where you can install all the dependencies that are needed at build-time
17prepare_build_container = [
18    # Example: npm, gcc, ...
19]
20
21# (Optional) Additional commands after all the app files are copied to the container
22build_steps = []

Configuration Fields

App Metadata

  • identifier - name of the app in Java-like format (with dots as separators; e.g., com.my_company.my_app)
    • com.luxonis namespace is reserved for official apps
    • com.example namespace is not recommended for production apps
  • app_version - version of the app in format major.minor.patch (e.g., 1.0.0)

App Build and Runtime Configuration

  • entrypoint - array of strings (a command in argv format)
  • cwd - (optional, default is / ) current working directory for the container
  • shell - (optional, default is ["/bin/bash", "-c"] ) shell to use for executing build_steps, entrypoint, and RUN commands in prepare_container and prepare_build_container sections
  • app_dir_name (optional/advanced; default is app ) - directory inside the container where the app files are copied; use only if you already use this directory name for something else

App Layers

Similar to Docker, an app is built in multiple layers:
  1. Base Image layer (specified in base_image section)
  2. Runtime layer (built in prepare_container section)
  3. Build layer (built in prepare_build_container section; this layer is disconnected from runtime layer after build)
  4. App layer (all the files from the app's directory and the build_steps are executed here)
Next to App layer, there are two additional parallel layers:
  • Static Frontend layer (if specified in static_frontend section)
  • DepthAI Models Cache layer (if specified in depthai_models section)
If any of these layers change, all the subsequent layers are rebuilt. Parallel layers are rebuilt independently of each other as they do not have mutual dependencies.

Base Image

The default base image is debian/bookworm-slim, pulled from registry-1.docker.io. The full base_image configuration looks like this:
Toml
1[base_image]
2api_url = "https://registry-1.docker.io" # Optional: Service https address
3service = "registry.docker.io" # Optional: Name of Image Registry Service
4image_name = "library/debian"
5image_tag = "bookworm-slim"
6
7oauth_url = "https://auth.docker.io/token" # Optional: address to oauth 2.0 token for this service
8auth_type = "repository" # Optional: scope type
9auth_name = "library/debian" # Optional: name of resource

Using a Custom Base Image

If you already develop with Docker, you can reuse that work in OAK Apps by pointing base_image to your own image. This is useful when you want to iterate on OS packages, runtimes, or shared dependencies in a familiar Docker workflow first, and then package the final app with oakapp.toml.This can also be a good fit when you are developing a reusable base environment and want to share it across multiple apps. Use a custom base image for stable, shared environment setup, and use prepare_container and prepare_build_container for app-specific runtime and build steps.To use a different image as the base layer, define it in oakapp.toml like this:
Toml
1[base_image]
2image_name = "myorg/my-base"
3image_tag = "latest"
By default, images are pulled from Docker Hub, but you can also point base_image to a different registry using the api_url field.

Self-Hosting a Container Registry

To avoid Docker Hub rate limits, you can self-host a container registry and point base_image.api_url to it during development.Run a registry that is reachable from the device:
Command Line
1docker run --rm -d -p 5000:5000 --name registry registry:2
Build and push an image to the local registry
Sh
1echo "FROM ubuntu:26.04" > ./Dockerfile
2docker buildx build --platform linux/arm64 -t myapp-base:latest --load .
3docker tag myapp-base:latest localhost:5000/myapp-base:latest
4docker push localhost:5000/myapp-base:latest
Use the base image in the oakapp. Add the [base_image] section in oakapp.toml like this:
Toml
1[base_image]
2api_url = "http://<self-hosted-registry-ip>:5000" # Service http address visible from the device
3image_name = "myapp-base"
4image_tag = "latest"
Keep in mind that the app is built on the device, so the registry must be accessible from the device. The base_image.api_url has to point to the device's network-accessible address. For the uploaded image to work on an OAK4 device it has to be uploaded as a linux/arm64 image.

Runtime And Build Layer

Both prepare_container and prepare_build_container are arrays of commands that are executed in the container to prepare the respective layers. The only difference is that the build layer is not present at runtime.The available command types are:
  • RUN - run a command in the container
Toml
1prepare_container = [
2    { type = "RUN", command = "apt-get update" },
3    { type = "RUN", command = "apt-get install -y python3-pip" },
4]
  • COPY - copy a file from the app's directory to the container sooner than in the App layer. This is useful for copying dependency files like requirements.txt. It is not necessary to copy the actual app files here, as they are copied later in the App layer.
    • source - path to the source file relative to the app's directory on the host
    • target - path to app directory inside the container (relative to app_dir_name if specified)
Toml
1prepare_container = [
2    { type = "COPY", source = "requirements.txt", target = "requirements.txt" },
3]

App Layer

First, all the files from the app's directory are copied to the container (into app_dir_name if specified). Then, the commands in build_steps are executed in order.
  • build_steps - steps to build an application or other preparation commands to be executed (array of strings)
Toml
1build_steps = [
2    "g++ -o /app/my_app /app/main.cpp",
3    "chmod +x /app/my_app",
4]
You can ignore files from being copied to the container by adding a .oakappignore file to your app's directory. The syntax is similar to .gitignore. Example:
Plain Text
1# Ignore all .log files
2*.log
3# Ingore node_modules/ directory
4node_modules/

Mounts

Mounts allow you to link directories or devices from the device running the app into the app's container. You cannot mount directories from the host this way. Mounts that are required must be present at both build time and run time.
  • required_mounts, required_devices - mounts that are required - if not present on startup of container, the app is stopped with error
Syntax is source[:target[:options]]; defaults:
  • source=target
  • options="rbind,rw"
  • All mount paths must be absolute. Relative paths are rejected for required_mounts, required_devices, optional_mounts, optional_devices, and additional_mounts (source/target).
Example:
Toml
1required_mounts = [
2    "/data/my-storage:/app/storage:rw,rbind",
3]
  • optional_mounts, optional_devices - if not present of startup of container, these mounts are ignored
  • additional_mounts ( source , target , type , options , required ) array of objects, see below for example:
Toml
1additional_mounts = [
2    { source = "/run/user/1000/pulse", target = "/run/user/1000/pulse", type = "none", options = [
3        "rbind",
4        "rw",
5    ], required = true },
6    { source = "/home/root/.config/pulse/cookie", target = "/root/.config/pulse/cookie", type = "none", options = [
7        "bind",
8        "ro",
9    ], required = true },
10]
  • additional_build_mounts - same as additional_mounts, but only for build time; these mounts are not present at runtime
  • allowed_devices - list of devices that the app is allowed to access inside the container
Toml
1allowed_devices = [{ allow = true, access = "rwm" }]

Static frontend

Static frontend layer allows you to build and serve a static web frontend alongside your app. See example on GitHub.
  • static_frontend
    • dist_path - path to the built frontend files (relative to the app's directory on the host)
      • build (optional) - build configuration for the frontend
        • source_path - path to the frontend source files
        • steps - array of commands to build the frontend
Toml
1[static_frontend]
2dist_path = "./frontend/dist" # path to the built frontend files
3
4[static_frontend.build]
5source_path = "./frontend" # path to the frontend source files
6steps = ["cd /app/frontend/src && npm install && npm run build"]
  • assign_frontend_port - if set to true, an available port will be assigned to OAKAPP_STATIC_FRONTEND_PORT environment variable inside the container; this can be used even if static_frontend is not specified
Toml
1assign_frontend_port = true
  • static_frontend_dir_name (optional/advanced; default is static_frontend) - directory inside the container where the static frontend files are mounted (will be stored in OAKAPP_STATIC_FRONTEND_PATH environment variable); use only if you already use this directory name for something else

DepthAI Models Cache

This section allows you to specify a folder with DepthAI models in *.yaml format that will be cached inside the container during build time. This way, you can create apps that work offline without the need to download models at runtime.
  • depthai_models
    • yaml_path - path to the DepthAI models folder in *.yaml format
    • use_only_cache - if set to true, only the cached models will be used, and no new models will be downloaded at runtime (sets DEPTHAI_ZOO_INTERNET_CHECK environment variable)
Toml
1depthai_models = { yaml_path = "./backend/src/depthai_models" }
  • depthai_models_dir_name (optional/advanced; default is depthai_models) - directory inside the container where the DepthAI models are mounted; use only if you already use this directory name for something else

Environment Variables and Build Arguments

Environment variables are set for runtime only.
Toml
1[env]
2MY_ENV_VAR = "some_value"
3ANOTHER_ENV_VAR = "another_value"
Build arguments are set only during build time and are not available at runtime.
Toml
1[arg]
2MY_BUILD_ARG = "some_build_value"
3ANOTHER_BUILD_ARG = "another_build_value"
Both environment variables and build arguments have lower precedence than the variables set by the user in command line (oakctl app run --env MY_ENV_VAR=value).