Reproduce Your Ubuntu Development Environment in Seconds with a Single YAML

What is Workshop?

Workshop, released by Canonical in May 2026, defines a development environment as a YAML file that specifies the base Ubuntu image, SDKs and optional actions. After committing the definition, any machine with Workshop installed can launch an identical sandbox with a single command.

name: dev
base: [email protected]
sdks:
  - name: ollama
    channel: vulkan/stable

Running workshop launch dev creates the environment in seconds.

Underlying technologies

LXD unprivileged system containers : the runtime runs the sandbox in an unprivileged container, minimizing the attack surface.

snapd interface system : containers must explicitly plug interfaces (Desktop, SSH, GPU, etc.) to access host resources; otherwise access is denied.

SDKs and SDK Store

The smallest composable unit is an SDK, published in an SDK Store. Available SDKs include: ollama – local large‑model execution (CPU / CUDA / ROCm / Vulkan) opencode – AI coding assistant nvidia – NVIDIA GPU toolchain (CUDA) amd – AMD GPU toolchain (ROCm) intel – OpenVINO inference acceleration ros2 – Robot Operating System

Adding an SDK is a single line in the YAML file.

Pain points addressed by Workshop

Slow environment setup : manual dependency installation can take hours; Workshop reduces it to one launch command.

Collaboration inconsistency : “works on my machine” issues disappear because the YAML is version‑controlled.

AI‑agent risk : agents run in an unprivileged container and cannot access host resources unless an interface is explicitly granted.

Upgrade failures : modifying the YAML and running workshop refresh rolls back automatically on error.

“For developers it’s convenient, but that doesn’t mean it’s safe for AI agents.” – Dmitry Lyfar, Canonical Engineering Manager

Core features

Composable and reproducible

The YAML definition can be stored in Git. Team members clone the repository and run workshop launch to obtain an identical environment. SDKs can be switched between stable and edge channels, and a sketch SDK allows local experimentation without affecting the main environment.

Agent‑ready sandbox

The sandbox runs in an unprivileged container, so AI agents cannot reach the host desktop, SSH agent, GPU or other resources unless the corresponding interface is explicitly plugged.

Unified host‑resource access

Workshop provides a standard interface system; a few configuration lines expose host mounts, devices and network services to the container. Supported interfaces include Desktop, SSH, GPU (NVIDIA/AMD), Camera, Mount, Tunnel, etc.

Suitable scenarios

AI/ML and agentic engineering – quick launch of Ollama, CUDA, OpenCode with isolated experimental libraries.

Robotics and IoT – ROS 2, cross‑compilation toolchains, multiple Ubuntu versions.

Education – instructors share a YAML file; students get 100 % identical labs.

Team collaboration – environment definition versioned in the repository; new hires launch instantly.

CI / deployment pipelines – same definition used locally and in the cloud prevents “works locally, fails in pipeline”.

Local GitHub Actions – full GitHub Actions workflows can be executed inside Workshop before pushing.

Step‑by‑step tutorial

Prerequisite

Workshop requires LXD 6.8 or newer. It runs on Ubuntu, other snap‑compatible Linux distributions, and WSL2 (Btrfs recommended).

# Ensure LXD version is sufficient
sudo snap install --channel=6/stable lxd

Installation

sudo snap install --classic workshop

Initialize a workshop

In the project directory run:

# Create a workshop named dev, based on Ubuntu 24.04, with the CPU version of Ollama
workshop init dev --sdks ollama/cpu/stable --base [email protected]

This creates .workshop/dev.yaml. Commit the .workshop/ directory to Git but ignore .workshop.lock.

Launch and inspect

# List workshops (initially Off)
workshop list

# Launch the sandbox
workshop launch dev

# Show environment details
workshop info dev

After launch the status changes to Ready and the project directory is automatically mounted at /project inside the container.

Work inside the sandbox

# Execute a command inside the container
workshop exec dev -- ollama pull tinyllama

# Open an interactive shell (user "workshop", project at /project)
workshop shell dev

# Stop or restart without destroying the environment
workshop stop dev
workshop start dev

Refresh the environment

Modify dev.yaml (e.g., change the base image or upgrade an SDK) and run: workshop refresh dev Refresh is transactional – on failure it automatically rolls back to the previous snapshot. Manual rollback is possible with workshop restore.

Define reusable actions

Common commands can be added to the actions section of the YAML and invoked with workshop run:

name: dev
base: [email protected]
sdks:
  - name: ollama
    channel: vulkan/stable
actions:
  pull: ollama pull "$@"

# Equivalent to running "ollama pull llama3" inside the container
workshop run dev -- pull llama3

IDE integration

VS Code – remote connection directly into the Workshop container.

JetBrains Gateway – one‑click remote development.

JupyterLab – run notebooks in the browser.

Git / GitHub Actions – full local Git workflow, including local execution of Actions.

Track changes (optional)

# List all atomic operation records
workshop changes

# Show tasks for a specific change (e.g., download base, pull SDK, run hook)
workshop tasks 4

These commands help pinpoint the exact step that failed.

Security model

The sandbox runs in an unprivileged container that cannot touch the host filesystem by default.

Access to Desktop, SSH, GPU and other host resources requires explicit interface plugging; un‑plugged interfaces are denied.

A uniform resource‑allocation model reduces human error across environments.

“You grant an agent only the capabilities you explicitly enable.” – paraphrased from the author’s remarks.

Conclusion

Workshop turns “environment as code” into a minimal workflow: a single YAML file plus one command yields seconds‑level reproducibility, cross‑machine consistency and secure isolation for AI agents. It is useful for developers frustrated by manual setup, AI researchers running experiments, educators teaching reproducible labs, and tech leads managing team collaboration.