This is the first section of the :ref:`four-part series <tut_index>`; a practical introduction that takes you on a tour of the essential |ws_markup| activities.
A workshop is a development environment running in a container, mapping your project to its contained dependencies. Here, you will practice all the major steps in the lifecycle of a workshop, from :ref:`defining <tut_define>`, :ref:`launching <tut_launch>`, and :ref:`refreshing <tut_refresh>` it to :ref:`executing commands <tut_exec>` and :ref:`shelling <tut_shell>` into the workshop. The steps you're about to perform cover most of your daily needs with |ws_markup|.
Install |ws_markup|, upgrading the prerequisites if needed, then ensure it runs.
|ws_markup| is supported on Ubuntu and other :program:`snap`-enabled Linux distributions; it is also compatible with Windows Subsystem for Linux (WSL2), where it uses Btrfs instead of ZFS for storage.
|ws_markup| relies on LXD 6.8+ for low-level operation and uses its REST API to handle individual workshops.
To install it from scratch with :program:`snap`:
$ sudo snap install --channel=6/stable lxdTo refresh an existing :program:`snap` installation:
$ sudo snap refresh --channel=6/stable lxdNote
If you prefer another installation method, see the available installation options in LXD documentation; after installation, make sure the LXD daemon is enabled and running. If in doubt, refer to LXD documentation and your distribution's manuals for guidance.
Install the snap using the --classic option:
$ sudo snap install --classic workshopNow you'll learn how to define, launch, start and stop a workshop.
First, you need to define a workshop. A definition is a YAML file that is stored in your project directory; it lists the components of the workshop to be instantiated at launch.
A definition can list many moving parts; perhaps, the most important are SDKs, which are basic, predefined building blocks of your development environment.
You reference SDKs from your workshop definition to specify what you want to include in your workshop. At runtime, |ws_markup| pulls and installs them, providing the dependencies and packages required for your work, while keeping the SDKs themselves isolated and manageable.
For demonstration purposes, assume we want to work with AI models using the Ollama platform. To do this, let's use the :samp:`ollama` SDK, which provides a local AI model server.
Before adding an SDK to a workshop, search the SDK Store to confirm it exists and check its publisher and current version:
$ sdk find ollama
NAME VERSION PUBLISHER SUMMARY
...
ollama 0.33.2 Canonical✓ Get up and running with large language modelsThe :samp:`✓` after the publisher's name marks a verified publisher.
The query also matches an SDK's title, summary, description, or publisher, so a broader keyword like :command:`sdk find ai` can surface AI-related SDKs on the Store, and :command:`sdk find agent` lists coding agents packaged as SDKs. Before running an agent in a workshop, learn :ref:`how to assess agent SDKs <ref_ai_agent_sdks>` and :ref:`what a workshop does and doesn't protect <security_coding_agents>`.
To see which channels and bases are available for a specific SDK, inspect its details:
$ sdk info ollama
name: ollama
publisher: Canonical✓
license: MIT
website: https://github.com/canonical/ollama-sdk
Get up and running with Llama 3.3, ...
CHANNELS
CHANNEL VERSION BUILD BASE REV SIZE
latest/stable 0.33.2 2026-09-03 [email protected] 149 1.47GB
[email protected] 147 1.47GB
[email protected] 148 1.47GB
...
cpu/stable 0.34.3 2026-09-23 [email protected] 163 17.38MB
[email protected] 164 17.38MB
[email protected] 165 17.38MB
cpu/candidate ↑
cpu/beta ↑
cpu/edge ↑The :samp:`CHANNELS` table lists each track (here, :samp:`latest`, :samp:`cpu`, :samp:`cuda`, :samp:`rocm`, and :samp:`vulkan`) at four risk levels (:samp:`stable`, :samp:`candidate`, :samp:`beta`, :samp:`edge`), the bases each revision supports, and its on-disk size. For this tutorial, we'll use :samp:`cpu/stable`, which runs on any machine without GPU hardware.
For the project directory, create a new Python repository:
$ mkdir ollama-python-project
$ cd ollama-python-project
$ git initEverything you handle with your workshop goes here: your Python code, custom assets, and so on.
In the project directory, scaffold a workshop definition with :command:`workshop init`, passing the base, the SDKs, and their channels on the command line:
$ workshop init dev --sdks ollama/cpu/stable --base [email protected]
"dev" workshop definition created at /home/user/ollama-python-project/.workshop/dev.yamlEach :option:`!--sdks` entry can take the :samp:`<NAME>/<CHANNEL>` form, so :samp:`ollama/cpu/stable` pins the :samp:`ollama` SDK to its :samp:`cpu/stable` channel. The command writes the definition to :file:`.workshop/dev.yaml`:
name: dev
base: [email protected]
sdks:
- name: ollama
channel: cpu/stableHere, the specific version to retrieve from the SDK Store comes from the :samp:`cpu/stable` channel of the :samp:`cpu` track.
To confirm that |ws_markup| sees the definition, list the workshops in the project directory:
$ workshop list
WORKSHOP STATUS NOTES
dev Off -Note
|ws_markup| ships shell completion for Bash, Zsh, Fish, and PowerShell; if you installed via snap, it is already enabled. Press Tab as you type any :program:`workshop` command to autocomplete subcommands, flags, and arguments.
Completion is context-aware: each command offers only values that make sense for it. For instance, :command:`workshop start` autocompletes from Stopped workshops only, :command:`workshop stop` from Ready ones, and :command:`workshop connect` autocompletes available plugs and then the matching slots.
As the command output suggests, your newly defined workshop is Off, so it needs to be launched.
Note
The command lists all workshops within the project; the tutorial focuses on a single-workshop setup, but your project can have multiple workshops defined.
For a detailed explanation of the workshop status values, see the :ref:`exp_workshop_status` section.
Note
The tutorial uses Ollama for demonstration purposes only. This doesn't imply that |ws_markup| is intended solely for AI; quite the contrary, it's envisioned as language-neutral and framework-agnostic.
To get a workshop ready for use, you launch it:
$ workshop launch
"dev" launchedOnce the workshop is launched, you can start using it to build, debug, and run your code.
After launching, check the runtime information to see what went into your workshop:
$ workshop info
name: dev
base: [email protected]
project: ~/ollama-python-project
hostname: dev.ollama-python-project.wp
status: ready
runtime: lxd-container
notes: --
sdks:
system:
installed: (1)
ollama:
tracking: cpu/stable
installed: 0.20.2 2026-04-15 (5)
mounts:
models:
host-source: .../6b79e889/dev/mount/ollama/models
workshop-target: /home/workshop/.ollama/modelsThe output looks like the :ref:`definition <tut_define>` with extra details such as the :ref:`mounts <tut_interfaces>`; ignore these for now.
While :command:`workshop info` shows the SDKs from one workshop's perspective, :command:`sdk list` reports every SDK volume currently stored on the machine, regardless of which workshop pulled it:
$ sdk list
NAME VERSION REV SIZE
ollama 0.20.2 5 15.22MB
system - 1 25.09kBEach row is a distinct SDK volume on disk. Until you launch a workshop that references an SDK, it won't appear here; at launch, |ws_markup| has pulled the SDK from the SDK Store and the revision shown matches the one in :command:`workshop info`.
After launch, |ws_markup| tracks the project directory using a hidden :file:`.workshop.lock` file that must remain in the project directory and not be copied or stored externally, e.g., in a repository.
You only need to launch a workshop once after defining it; after any substantial changes to it, you do a :ref:`refresh <tut_refresh>`. Otherwise, the workshop is just a fancy container that can be started and stopped.
The workshop starts automatically at launch, but you can also stop and restart it at will. Suppose you want to free up some resources, so you stop the workshop:
$ workshop stopThis changes the status of the workshop to Stopped.
To make it Ready again, start the workshop:
$ workshop startBoth commands work gracefully, waiting for the workshop to comply:
- :command:`workshop stop` doesn't destroy the workshop, unlike :ref:`remove <tut_remove>`
- :command:`workshop start` doesn't build it from scratch, unlike :ref:`launch <tut_launch>` or :ref:`refresh <tut_refresh>`
In the next step, you'll refresh an existing workshop.
Note
If issues arise now or later, see these guides: :ref:`how_troubleshoot` and :ref:`how_debug_issues_workshops`.
Note
Consider adding the :file:`.workshop.lock` file to your :file:`.gitignore` or similar ignore files:
$ echo ".workshop.lock" >> .gitignoreIn contrast, the :file:`.workshop/` directory, which holds your definition, is meant to be stored in a repository; if your :file:`.gitignore` file uses rules such as "ignore everything except these files and directories," add them to the list of explicitly tracked items.
Sometimes the base or the SDKs listed in your :ref:`workshop definition <tut_define>` are updated by their publishers. Alternatively, you may have changed the definition to switch bases, add and remove SDKs, or toggle their channels. A good example is when a new Ubuntu LTS version is released and, as a result, a new base image becomes available. In either case, you must refresh the workshop to apply the updates.
For example, change the base and the SDK channel in your definition and refresh the workshop:
name: dev
base: [email protected]
sdks:
- name: ollama
channel: vulkan/stable$ workshop refreshAfter the refresh, :command:`sdk list` may show multiple revisions of :samp:`ollama` if the previous :samp:`cpu/stable` volume is still on disk alongside the freshly pulled :samp:`vulkan/stable` one.
Running :command:`workshop refresh` is similar to a :ref:`launch <tut_launch>`. However, it ensures the workshop remains operational. If issues occur, a refresh rolls back to a previous stable condition, whereas a failed launch has no condition to revert to and just fails.
SDKs in a workshop diagnose themselves during launch and refresh; if an SDK fails to set up, the entire change is rolled back to keep the workshop operational.
Finally, to discard any changes made inside the workshop since the last successful launch or refresh, run :command:`workshop restore`. Unlike the automatic rollback on a failed refresh, this is a deliberate action that reverts the workshop to the most recent snapshot and resets it to its default state.
Now that you can launch, refresh, start and stop a workshop, let's move on to more practical purposes.
When the workshop is Ready, you can run arbitrary commands in it. In this tutorial, we're working with Ollama AI models, and we've already created a Python project directory to serve as our workspace.
First, let's put our example workshop to practical use; download a simple AI model inside the workshop using the :command:`workshop exec` command. We'll use the :samp:`tinyllama` model, which is small and quick to download:
$ workshop exec dev -- ollama run tinyllamaThis downloads and then runs the :samp:`tinyllama` model. The model will be stored in the mounted :file:`models/` directory, so it persists between workshop refreshes. Quit the Ollama console by pressing :samp:`Ctrl+D`.
You can also list the available models:
$ workshop exec dev -- ollama list
NAME ID SIZE MODIFIED
tinyllama:latest 2644915ede35 637 MB 24 seconds agoFurthermore, your work files and deliverables, however complex they may be, can reside on the host system, while the toolchain is transparently confined and managed by |ws_markup|. This enables you to focus on your project, switching when needed between language and framework versions or base images.
Next, we'll explore the remaining aspects of your daily workshop usage.
Note
|ws_markup| also integrates with modern IDEs. For instance, see :ref:`how_vscode_connect_remote` for the VS Code extension.
Besides running individual commands, you can open an interactive shell if you need to perform multiple operations within a session. |ws_markup| runs the login shell for the default nonprivileged user, who's also named :samp:`workshop`:
$ workshop shell
workshop@dev:/project$ pwd
/project
workshop@dev:/project$ lsb_release -a
...
Distributor ID: Ubuntu
Description: Ubuntu 24.04.3 LTS
Release: 24.04
Codename: noble
workshop@dev:/project$ exitFor complex commands that you run often, define actions in your workshop definition to invoke them with :command:`workshop run`.
Add an :samp:`actions` section to :file:`.workshop/dev.yaml`:
name: dev
base: [email protected]
sdks:
- name: ollama
channel: vulkan/stable
actions:
pull: ollama pull "$@"The :samp:`"$@"` expansion forwards every argument supplied after the action name into the action's :program:`bash` script.
Pull a model through the new action; :samp:`"$@"` forwards :samp:`tinyllama` into :command:`ollama pull`:
$ workshop run dev -- pull tinyllamaFinally, actions are parsed on every :command:`workshop run`, so there's no need to refresh the workshop after editing them.
Note
See :ref:`how_add_actions` for more on writing and running actions.
Remember that the project directory is mounted as :file:`/project/` when the workshop is launched; any changes to :file:`/project/` from inside the workshop are visible in the project directory, and vice versa:
$ touch created_outside.txt
$ workshop exec dev -- ls /project/
... created_outside.txt ...
$ workshop exec dev -- touch /project/created_inside.txt
$ ls
... created_inside.txt created_outside.txt ...Next, let's dive into how changes and tasks work to track your workshop activities.
To see how |ws_markup| keeps track of its activities around a project, check out the recent major operations, or changes, with :command:`workshop changes`:
$ workshop changes
ID STATUS SPAWN READY SUMMARY
1 Done today at 09:26 CET today at 09:27 CET Launch "dev" workshop
...
4 Done today at 09:32 CET today at 09:34 CET Refresh "dev" workshopChanges are enacted atomically to ensure workshops stay operational. Any change must have all its smaller steps, or tasks, succeed; otherwise, it will be reverted.
To look at the latest change, run the :command:`workshop tasks` command without an argument. To find out which tasks went into a certain change, pass the change ID to the command:
$ workshop tasks 4
STATUS DURATION SUMMARY
Done 2m17.389s Download "[email protected]" base image
Done 113ms Retrieve "system" SDK
Done 2m59.777s Retrieve "ollama" SDK from channel "vulkan/stable"
Done 443ms Create SDK state storage
Done 581ms Run hook "save-state" for "system" SDK
Done 449ms Run hook "save-state" for "ollama" SDK
Done 54ms Disconnect interfaces of "ollama" SDK
...
Done 528ms Setup "system" SDK profileThis lists all the tasks and includes logs for some of them; each task expresses a simple token of logic, such as running a hook or connecting an interface.
This was the last step in this tutorial section; you are now familiar with the essential operations provided by |ws_markup| and have had your first taste of what it can do for you.
Your next step is to learn how to work with interfaces; proceed to the :ref:`tut_work_with_interfaces` section.