Applications#

Overview#

AI Workbench manages applications that run in or alongside the project container.

You configure an application with start/stop commands and port information, and AI Workbench handles the lifecycle: starting, stopping, health checking, and status monitoring.

You don’t manually start/stop containers, run servers or manage port forwarding.

Application configurations are stored in the spec file and versioned with the project.

Anyone who clones the project gets the same application definitions. Adding or removing an application through the Desktop App modifies .project/spec.yaml.

AI Workbench proxies web applications to a local URL for browser access.

The proxy runs on port 10000 and routes requests to applications in the container. You access remote applications the same way as local ones — through the Desktop App on your local machine.

Applications must be installed in the project before AI Workbench can manage them.

You add dependencies to your requirements files and code to the repository, then configure the application definition (name, type, commands, port).

Key Concepts#

Web App: A web application running in the project container, accessed through the proxy. Requires start/stop commands, port, and optional URL configuration. Examples: JupyterLab, TensorBoard, custom dashboards.
Process: A background application running in the project container without a web interface. Requires start/stop commands but no port. Examples: training scripts, data processing pipelines.
Compose App: A multi-container application defined in a compose file. Each service runs in its own container with shared networking. Requires a valid Docker Compose v2 file.
Native App: A system application on the host that connects to the project container. VS Code and Cursor are the primary examples. Configuration varies by OS and container runtime.
Application Proxy: AI Workbench’s Traefik-based reverse proxy on port 10000. Routes browser requests to web apps in the container and injects PROXY_PREFIX into the app process so the app can be aware of its route.
Application Lifecycle: The stages an application goes through: configured, started, running, stopped. AI Workbench tracks state and provides controls through the Desktop App and CLI. Application state is session-based and resets when the container stops.

Preconfigured vs Custom Applications#

AI Workbench provides one-click setup for common development tools.

VS Code and Cursor can be added to any project from the Desktop App and launched from the Application Launcher. JupyterLab ships preinstalled in the NVIDIA base images, so it is ready to use immediately.

Windsurf works with AI Workbench but does not have direct integration yet. You start the project container and attach Windsurf manually.

Custom applications require you to provide the configuration.

You specify the name, class (web app or process), start command, stop command, and port (for web apps). AI Workbench validates the configuration and stores it in the spec file.

Preconfigured and custom applications work the same way once configured.

Start, stop, monitor, and access them through the Desktop App or CLI.

Where Applications Are Defined#

Base image apps live in environment.base.apps.: These are built into the container image. NVIDIA base images include JupyterLab and TensorBoard here. Manual edits to this section are overridden when the environment version is updated.
Custom apps live in execution.apps.: These are not part of the base image. You add them through the Desktop App, CLI, or by editing the spec file directly.
Compose apps are defined in a separate compose file, not in the spec.: The spec file only stores the path to the compose file through environment.compose_file_path.

Accessing Applications#

Web app URLs are temporary and session-specific.: The proxy URL is valid while the application is running and the Desktop App is connected. Restarting the application generates a new URL.
The proxy works the same for local and remote locations.: For remote locations, AI Workbench establishes an SSH tunnel to the proxy automatically. You access remote apps from the Desktop App on your local machine.
Processes don’t have URLs.: Monitor them through the Desktop App or CLI. Use processes for tasks that produce output files or side effects.