Applications#
Overview#
- AI Workbench manages applications that run in the project container.
You can configure development tools (JupyterLab, VS Code), dashboards (TensorBoard), custom web apps, background processes, or multi-container applications.
AI Workbench handles start/stop, proxying, and status monitoring. You don’t manually run servers or manage port forwarding.
- Applications are configured per project and stored in version control.
Each project defines managed applications in the spec.yaml.
The application configuration is part of the the environment configuration. Anyone can launch it without manually configuring ports or start commands.
- AI Workbench proxies web applications to a local URL for access in your browser.
Starting a web app in the Desktop App makes it accessible through a local URL.
You don’t need to remember port numbers or configure SSH tunnels to remote servers. Click the application card in the Desktop App or use the CLI to get the access URL.
- Applications must be installed in the project before AI Workbench can manage them.
You add application dependencies to your project’s requirements files and include any necessary code in the repository.
Once installed, you configure the application by providing start/stop commands and port information. AI Workbench then manages the application lifecycle through the UI or CLI.
Key Concepts#
- Web App
An application with a web interface that runs in the project container. Examples include JupyterLab, TensorBoard, and custom dashboards. Requires start/stop commands, port number, and optional URL path configuration.
- Process
A background application or script that runs in the project container without a web interface. Examples include monitoring scripts, data processing pipelines, or training loops. Requires start/stop commands but no port configuration.
- Compose App
A multi-container application defined in a Compose File. Each service in the compose file runs in its own container with shared networking. Requires a valid compose file at the repository root with properly named services.
- Native App
A system application that runs on your host machine with access to the project container. VS Code is the primary example, connecting to the container as a remote development target. May require manual configuration steps depending on your OS and container runtime.
- Application Proxy
AI Workbench’s built-in HTTP proxy that makes containerized web apps accessible in your browser. Automatically maps container ports to host URLs without manual port forwarding. Works for both local and remote locations through the Desktop App.
- Application Lifecycle
The stages an application goes through: configured –> started –> running –> stopped. AI Workbench tracks application status and provides controls for starting, stopping, and viewing logs. Application state is session-based.
Built-in vs Custom Applications#
- JupyterLab and VS Code are built-in applications.
AI Workbench provides pre-configured application definitions for these common development tools. If they’re not already in your project, you can add them with a single click in the Desktop App. The base images include JupyterLab by default, so it’s ready to use immediately.
- Custom applications require manual configuration.
You specify the application name, type (web app or process), start command, stop command (optional), and port (for web apps). AI Workbench validates the configuration and stores it in your project’s spec.yaml file. Once configured, custom applications work the same as built-in onesstart, stop, monitor through the UI.
- VS Code requires additional setup steps.
Because VS Code is a native application running on your host, it needs to connect to the container runtime. Configuration varies by OS and whether you’re using Docker or Podman. AI Workbench provides guidance through the setup process and verifies the connection.
Accessing Applications#
- Web apps are accessible through AI Workbench’s proxy.
When you start a web app, the Desktop App displays an access URL on the application card. Click the URL to open the app in your browser, or copy it for use elsewhere. The proxy works for both local and remote locationsyou access remote apps through the Desktop App on your local machine.
- Application URLs are temporary and session-specific.
The proxy URL is valid while the application is running and the Desktop App is connected. If you stop the application or close the Desktop App, the URL becomes inaccessible. Restarting the application generates a new access URL.
- Processes don’t have URLs.
Background processes run without a web interface, so there’s no URL to access. Monitor their status and view logs through the Desktop App or CLI. Use processes for tasks that produce output files or side effects rather than interactive interfaces.
Multi-Container Applications#
- Compose apps run multiple containers as a single application.
Each service defined in the compose.yml file runs in its own isolated container. Services share a network and can communicate using service names as hostnames. This architecture supports complex applications with separate frontend, backend, and database containers.
- AI Workbench uses Docker Compose profiles to manage services.
Profiles let you define which services run together as a logical unit. If no profile is specified, Docker Compose runs the default profile. This enables different deployment scenariosrun only the services you need for a particular workflow.
- Compose apps require a valid compose file at the repository root.
The file must use Docker Compose v2 syntax and have properly named services. AI Workbench validates the compose file when you configure the application. Changes to the compose file require restarting the application to take effect.
Version Control and Portability#
- Application configurations are stored in version control.
Web apps, processes, and native apps are defined in .project/spec.yaml. Compose apps are defined in their .compose.yml file. Both files are tracked in Git, so application configurations travel with your project.
- Adding or removing applications creates Git changes.
When you add an application through the Desktop App, it modifies .spec.yaml. Deleting an application removes its entry from .spec.yaml. You commit these changes like any other project modification.
- Application dependencies must be reproducible.
If your application requires specific packages, add them to .requirements.txt or .apt.txt. If it needs setup scripts, include them in the repository. Without versioned dependencies, teammates won’t be able to run your application when they clone the project.