Skip to navigation
How To GuidesEnvironments

Use the onStart.bash Script

View as Markdown

Overview

AI Workbench removes the project container when you stop a project and creates a new container when you start it again.

Your project files and container image persist outside the temporary container, but changes made only in the running container do not. Use startup customization to initialize each newly created container after AI Workbench mounts the project.

The onStart.bash script runs each time your project container starts.

Use it to initialize the running container, prepare project directories, or start background services. AI Workbench runs the script from the mounted project after the base-image entrypoint finishes. The script runs as the project user with temporary passwordless sudo access.

The script is different from the preBuild.bash and postBuild.bash scripts.

Build scripts customize the container image and require a rebuild to apply changes. The onStart.bash script customizes a running container and can access the mounted project files.

Changes to the script take effect the next time the project container starts.

Stop and start the project to create a new container and run the updated script from the mounted project. You do not need to rebuild an already-migrated project solely because you changed onStart.bash.

Use build scripts for changes that belong in the container image.

Installing the same packages at every startup makes startup slower and can produce different results over time. Put repeatable image customization in preBuild.bash or postBuild.bash instead.

Key Concepts

onStart.bash

An optional bash script in the project root that runs at each project container start.

Generated Entrypoint

An entrypoint.sh file that AI Workbench dynamically renders into the build context when it builds the container image. The generated entrypoint coordinates the base-image entrypoint, project onStart.bash script, and transition to the normal project container process. AI Workbench does not store this generated file in the project repository.

Base-Image Entrypoint

A startup script supplied by the base image and preserved by AI Workbench. AI Workbench runs it before the project onStart.bash script.

Passwordless Sudo

AI Workbench runs onStart.bash as the project user with passwordless sudo available. AI Workbench removes passwordless sudo after the script finishes. Passwordless sudo is not available in the normally running project container after startup.

Startup Order

AI Workbench completes startup actions in a fixed order.

  1. Start the AI Workbench-generated entrypoint.
  2. Run the preserved base-image entrypoint, when the base image defines one.
  3. Run the project-root onStart.bash script as the project user.
  4. Remove passwordless sudo access from the project user.
  5. Continue with the normal project container process.

Edit onStart.bash in the Desktop App

Step One: Open the startup script.

  1. Select Project Tab > Project Container > Scripts.
  2. Select onStart.bash.
  3. Select Edit Script.

Step Two: Add your startup commands.

  1. Enter your bash commands in the editor.
  2. Select Save.

Step Three: Restart the project container.

  1. Stop the project container if it is running.
  2. Start the project container.

Success: AI Workbench runs the updated script while the project container starts.

Edit onStart.bash with the CLI

Step One: Open the startup script in your configured editor.

Run:

nvwb edit script onStart.bash

Step Two: Save the script and restart the project container.

Stop and start the project with the Desktop App or CLI.

Success: AI Workbench runs the updated script during the next project container start.

Edit onStart.bash Directly

Step One: Edit onStart.bash in the project root.

Open onStart.bash in a text editor and add your startup commands.

Step Two: Save the script and restart the project container.

Stop and start the project with the Desktop App or CLI.

Success: AI Workbench runs the updated script during the next project container start.

Example Startup Script

Write startup commands so that they can run safely more than once.

The following example prepares a system cache directory and an output directory in the default project mount:

#!/bin/bash
set -euo pipefail
sudo mkdir -p /opt/project-cache
sudo chown "$(id -u):$(id -g)" /opt/project-cache
mkdir -p /project/output

Startup Failures and Timeouts

The startup script must finish before AI Workbench completes project container startup.

Do not use the script to run a permanent foreground process. Start a service in the background when it must continue running after the script finishes.

A script error, container termination, or long-running command can prevent startup from completing.

Review the startup output, correct the failing command, and stop and start the project container again. AI Workbench reports container termination as an error and reports a startup stage that takes too long as a timeout warning.

Existing Projects

An existing project might require one container rebuild before it supports onStart.bash.

AI Workbench migrates the generated container entrypoint that invokes the script. After that migration, editing onStart.bash does not require another rebuild solely for the script change.