Workshop

https://github.com/canonical/workshop
Admin
Workshop provides secure, fast, and composable development environments that are agent-ready,...
Tokens:202,268
Snippets:1,919
Trust Score:9.5
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and start LXD

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/fix-workshops/fix-installation.rst

Install LXD from the 6/stable channel, enable and start the lxd.daemon service, and verify its status. This is a major prerequisite for Workshop.

```console
$ sudo snap install --channel=6/stable lxd
$ sudo snap start --enable lxd.daemon
$ sudo snap services lxd

```

--------------------------------

### setup-base example: uv SDK system-wide configuration

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.rst

This shell script configures the uv SDK system-wide in the setup-base hook. It creates a virtual environment, updates PATH, installs shell completions, and sets up a pip alternative. This runs once at SDK install or refresh, and its operations become part of workshop snapshots.

```shell
sudo -u workshop mkdir -p /home/workshop/uv-venv

cat <<EOF >> /etc/profile.d/uv.sh
PATH="$SDK/bin:\$PATH"
EOF

"$SDK"/bin/uv generate-shell-completion bash > /etc/bash_completion.d/uv.sh
"$SDK"/bin/uvx --generate-shell-completion bash > /etc/bash_completion.d/uvx.sh

mkdir -p /usr/local/libexec/alternatives

cat << 'EOF' > /usr/local/libexec/alternatives/uv-pip
#!/bin/bash
exec uv pip "$@"
EOF

chmod +x /usr/local/libexec/alternatives/uv-pip
update-alternatives --install /usr/bin/pip pip /usr/local/libexec/alternatives/uv-pip 50
```

--------------------------------

### Extract common test setup into helpers

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Extract common test setup into helper functions and shared constants. This example defines a readyWorkshopJSON constant and a setupReadyWorkshop helper to reduce duplication while keeping tests self-contained.

```go
const readyWorkshopJSON = `{
    "name": "dev",
    "status": "Ready"
}`

func (s *testSuite) setupReadyWorkshop(c *check.C) Workshop {
    return Workshop{Name: "dev", Status: "Ready"}
}
```

--------------------------------

### setup-project: Install and start user systemd service

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.rst

Typical setup-project hook that installs a service unit and enables it as a user-level systemd service. Runs as the workshop user after setup-base. User-level services tie lifetime to the workshop user's session and avoid sudo.

```shell
install -D --mode=644 --target-directory ~/.config/systemd/user \
    "$SDK/<NAME>.service"

systemctl --user daemon-reload
systemctl --user enable --now <NAME>
```

--------------------------------

### setup-project example: comfy SDK GPU detection and PyTorch installation

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.rst

This shell script runs in the setup-project hook to detect the GPU type and install the appropriate PyTorch variant. It uses lspci to check for NVIDIA, AMD, or Intel GPUs and installs the corresponding torch packages. This is necessary because the GPU is only available after the workshop launches and interfaces are connected.

```shell
GPU_TYPE="none"

if command -v lspci >/dev/null 2>&1; then
    if lspci | grep -i 'NVIDIA' >/dev/null 2>&1; then
        GPU_TYPE="nvidia"
    elif lspci | grep -i 'AMD/ATI' >/dev/null 2>&1; then
        GPU_TYPE="amd"
    elif lspci | grep -i 'Intel.*Graphics' >/dev/null 2>&1; then
        GPU_TYPE="intel"
    fi
fi

echo "Detected GPU: $GPU_TYPE"
```

--------------------------------

### Show Bash completion help

Source: https://github.com/canonical/workshop/blob/main/cmd/internal/doctemplates/workshop.rst

Prints instructions for persistent Bash completion installation. Use to see per-shell setup steps.

```console
$ workshop completion bash --help
```

--------------------------------

### sdk info examples

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk.rst

Examples of using sdk info: basic info, restricting base, and showing all architectures.

```console
$ sdk info openvino
```

```console
$ sdk info openvino --base ubuntu@24.04
```

```console
$ sdk info openvino --arch all
```

--------------------------------

### sdk list examples

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk.rst

Examples of using sdk list: listing all volumes and hiding the table header.

```console
$ sdk list
```

```console
$ sdk list --no-headers
```

--------------------------------

### Install Spread from source

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Clones the Spread repository and installs it using Go. Ensure $GOPATH/bin is in your PATH.

```console
$ git clone https://github.com/canonical/spread
$ cd spread
$ go install ./...
```

--------------------------------

### Usage: workshop start

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-start.rst

Shows the command usage syntax for starting one or many workshops.

```console
$ workshop start <WORKSHOP>... [flags]
```

--------------------------------

### Initial sdk.yaml minimal setup

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.rst

The initial sdk.yaml file created by workshop sketch-sdk, containing empty hooks, plugs, and slots sections. This is the starting point for defining the sketch SDK.

```yaml
name: sketch

hooks:
 # ...
plugs:
 # ...
slots:
 # ...

```

--------------------------------

### Install LXD and Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Install LXD 6.8+ and Workshop via snap. The first command is skipped if LXD is already installed.

```console
sudo snap install --channel=6/stable lxd  # skip if LXD is already installed
sudo snap install --classic workshop
```

--------------------------------

### Dockerfile pattern for system and user setup

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/sdk-vs-dockerfile.rst

Shows a typical Dockerfile pattern for system setup as root followed by a switch to a non-root user for project setup. In Workshop, the root setup maps to the setup-base hook and the user-level setup maps to the setup-project hook, which runs as the workshop user after interfaces are connected and /project/ is mounted.

```docker
# System setup as root (≈ setup-base)
RUN apt-get update && apt-get install -y ...

# Switch to non-root user and set up the project (≈ setup-project)
USER appuser
WORKDIR /home/appuser
RUN pip install --user ...
```

--------------------------------

### Install Workshop snap

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.rst

Installs the Workshop snap using the --classic option.

```console
$ sudo snap install --classic workshop

```

--------------------------------

### Example: Initialize a new project

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-init.rst

Runs the init command with default settings to create an 'sdkcraft.yaml' file along with hooks and tests in the current directory.

```console
$ sdkcraft init
```

--------------------------------

### Launch workshop to install SDK

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/use-host-devices.rst

Launches the workshop to install the SDK. The custom device interface stays disconnected after launch for security reasons.

```console
$ workshop launch dev
```

--------------------------------

### Start a workshop

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.rst

Starts the workshop again, making it Ready. Does not build it from scratch.

```console
$ workshop start

```

--------------------------------

### sdkcraft release example promoting revision 8 to latest/stable

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/publish-an-sdk.rst

Example command to promote revision 8 to the latest/stable channel. Plain 'stable' and comma-separated lists like 'beta,edge' are valid channel arguments.

```console
$ sdkcraft release <NAME> 8 latest/stable
```

--------------------------------

### Install and enable Ollama systemd service

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.rst

Shell commands run during the setup-project phase to install the service file, reload systemd, and enable the service to start automatically.

```shell
install -D --mode=644 --target-directory ~/.config/systemd/user "$SDK/ollama.service"

systemctl --user daemon-reload
systemctl --user enable --now ollama
```

--------------------------------

### setup-base: Install packages with apt-get

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.rst

Terse apt-get commands for setup-base. apt is preconfigured to skip recommended/suggested packages and answer yes to prompts, so no extra flags are needed.

```shell
apt-get update
apt-get install build-essential cmake ninja-build
```

--------------------------------

### Example usage block

Source: https://github.com/canonical/workshop/blob/main/cmd/internal/doctemplates/command.rst

Displays an example usage of the command. The placeholder {{ .Usage | indent 3 }} is replaced with the actual example command, indented by three spaces, when the template is rendered.

```console
{{ .Usage | indent 3 }}
```

--------------------------------

### Install and initialize LXD for local snap builds

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/maintenance.rst

Install Snapcraft and LXD via snap, add the current user to the lxd group, and initialize LXD. These steps are required to build Workshop snaps locally in a self-launched LXD container.

```console
$ sudo snap install --classic snapcraft
$ sudo snap install --channel=6/stable lxd
```

```console
$ sudo usermod -a -G lxd $USER
```

```console
$ lxd init
```

--------------------------------

### Build and install the SDK with sdkcraft try

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.rst

Run this command to pack the SDK for each declared platform and copy the resulting <NAME>_<ARCH>_<BASE>.sdk files into the try area.

```console
$ sdkcraft try
```

--------------------------------

### Good Godoc conventions example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the recommended Godoc comment style: comments start with the name of the exported element. The comments for Workshop and Launch begin with the element names.

```go
// Workshop represents a development environment.
type Workshop struct { ... }

// Launch creates and starts a new workshop with the given configuration.
func Launch(cfg *Config) (*Workshop, error) { ... }
```

--------------------------------

### sdk find examples

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk.rst

Examples of using sdk find: single keyword, multiple words, and hiding the table header.

```console
$ sdk find openvino
```

```console
$ sdk find jupyter notebooks
```

```console
$ sdk find openvino --no-headers
```

--------------------------------

### Launch and run the documentation server

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/documentation.rst

Starts the local documentation server and serves it at 127.0.0.1:8000. Run these commands from the docs/ directory.

```console
$ workshop launch dev
$ workshop run dev docs-run
```

--------------------------------

### Tutorial paragraph example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example from a tutorial showing how to break complex topics into multiple paragraphs.

```restructuredtext
Install Workshop,
upgrading the prerequisites if needed,
then ensure it runs.

Authenticate to the Snap Store and install the snap
using the `--classic <...>`_ option:
```

--------------------------------

### Example workshop definition file

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Example .workshop/dev.yaml file generated by the init command. It defines the base image, SDKs, and a custom action that runs 'go vet ./...'.

```yaml
# .workshop/dev.yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: opencode
  - name: go
    channel: 1.26/stable
actions:                # add your own
  analyzer: |
    go vet ./...
```

--------------------------------

### Console example with sudo

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows how to include `sudo` explicitly when root access is required.

```restructuredtext
.. code-block:: console

   $ sudo snap install workshop --classic

```

--------------------------------

### Expected output from Ollama API test

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.rst

Example output showing the Ollama version and a generated response to the prompt, confirming the setup works.

```console
Ollama version: 0.9.6

The sky is blue due to its light absorption by the air and water molecules.
The atmosphere contains small amounts of carbon dioxide, which helps absorb
more blue-violet light from the sun. The amount of red light absorbed also
plays a role in determining the color of the sky. The exact combination of
these factors can vary between different regions around the world due to
changes in climate and topography. Additionally, some cultures have myths or
beliefs about what colors are associated with various things, such as green
for growth, blue for water, etc.

```

--------------------------------

### Install LXD with snap

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.rst

Installs LXD 6.8+ from the stable channel using snap. Required before installing Workshop.

```console
$ sudo snap install --channel=6/stable lxd

```

--------------------------------

### Install SDKcraft snap with --classic

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.rst

Installs the SDKcraft snap with the --classic option, which is required for the snap to function properly.

```console
$ sudo snap install --classic sdkcraft

```

--------------------------------

### Verify Spread installation

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Run spread -h to see the help message after installation.

```console
$ spread -h
```

--------------------------------

### Initialize workshops with different SDK channels

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Examples showing how to pin SDK versions using channels. The default is latest/stable, but you can specify a release line like Node.js 24 LTS or Go 1.25.

```console
workshop init web --sdks node            # latest/stable, the default
workshop init web --sdks node/24/stable  # pinned to the Node.js 24 LTS line
workshop init api --sdks go/1.25/stable  # pinned to the Go 1.25 release line
```

--------------------------------

### YAML configuration example with caption

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows a YAML configuration example with a caption. Always include a caption when it can be deduced from context.

```restructuredtext
.. code-block:: yaml
   :caption: workshop.yaml

   name: dev
   base: ubuntu@22.04
   sdks:
     - name: go
       channel: 1.26

```

--------------------------------

### Example: Pack the project

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-pack.rst

Runs the pack command with no options, which processes parts and creates the final artifact in the current directory.

```console
$ sdkcraft pack
```

--------------------------------

### workshop remount example

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop.rst

Example that remounts the mod-cache mount interface plug of the go SDK under the nimble workshop in the current project directory to ~/new-cache-mount/ on the host.

```console
$ workshop remount nimble/go:mod-cache ~/new-cache-mount
```

--------------------------------

### Metadata example: workshop introduction

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example metadata block from the documentation for a practical introduction to workshops.

```restructuredtext
.. meta::
   :description: Practical introduction to workshops, guiding users through
                 defining, launching, and refreshing workshops, and executing commands in workshops.
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Installs pre-commit so git runs the linters on every commit using the same pinned golangci-lint.

```console
$ pre-commit install
```

--------------------------------

### Consistent error handling - codebase examples

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Real-world examples from the codebase showing the consistent error handling patterns in use.

```go
// From cmd/workshopd/run.go
if err := dirs.CreateDirs(); err != nil {
    return err
}

// From cmd/sdk/main.go
if err := cmd.Execute(); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
}
```

--------------------------------

### Start single workshop (optional name)

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-start.rst

Starts the workshop when the project has only one workshop, making the name optional.

```console
$ workshop start
```

--------------------------------

### setup-base hook: export DOTFILES_SDK

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/write-runtime-hooks.rst

Runs as root before the project directory is mounted and before plugs and slots are connected. Use for system-wide preparation. The $SDK variable points to the SDK installation directory.

```shell
cat <<PROFILE >/etc/profile.d/dotfiles.sh
export DOTFILES_SDK="$SDK"
PROFILE
```

--------------------------------

### Refresh, stop, remount, and start the workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/add-mounts.rst

Shows the sequence of commands to apply a remount: refresh the workshop, stop it, remount the plug to a host path, then start it again. The stop/start is required when the host source is populated to avoid corruption.

```console
$ workshop refresh
$ workshop stop dev
$ workshop remount dev/uv:shared ~/datasets
$ workshop start dev

```

--------------------------------

### Example: List changes for all workshops

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-changes.rst

Lists recent changes for all workshops in the current project directory.

```console
$ workshop changes
```

--------------------------------

### Launch the workshop (console)

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.rst

Starts the Workshop environment that will be shared by all agents.

```console
workshop launch
```

--------------------------------

### Add setup-project hook to install jupyter-console

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.rst

Adds a setup-project hook to sdk.yaml that runs as the workshop user after the project directory is mounted and interfaces are connected. It activates the Jupyter virtual environment and installs jupyter-console.

```yaml
name: sketch

hooks:
  setup-project: |
    source /var/lib/workshop/sdk/jupyter/venv/bin/activate
    pip install jupyter-console

```

--------------------------------

### workshop info nimble example

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-info.rst

Lists details for the 'nimble' workshop in the current project directory.

```console
$ workshop info nimble
```

--------------------------------

### sdkcraft release examples

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft.rst

Releases a revision to a channel. The first example releases revision 8 to stable. The second releases revision 8 to latest/stable. The third releases revision 9 to multiple channels (beta and edge).

```console
$ sdkcraft release my-sdk 8 stable
```

```console
$ sdkcraft release my-sdk 8 latest/stable
```

```console
$ sdkcraft release my-sdk 9 beta,edge
```

--------------------------------

### Type switch example from codebase

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

An example from internal/asserts/constraint.go showing the type switch pattern in practice. It handles string and int types, returning an error for any other type.

```go
// From internal/asserts/constraint.go
switch x := v.(type) {
case string:
    return x, nil
case int:
    return strconv.Itoa(x), nil
default:
    return "", fmt.Errorf("invalid type %T", v)
}
```

--------------------------------

### Example: Pack to a specific output directory

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-pack.rst

Uses the --output flag to specify the output directory for created packages, here 'dist/'.

```console
$ sdkcraft pack --output dist/
```

--------------------------------

### Example: Create two tracks for the go SDK

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-create-track.rst

Creates two tracks (1.26 and 1.25) for the 'go' SDK. The command lists all tracks it creates, and tracks must match an existing guardrail for the SDK.

```console
$ sdkcraft create-track --track 1.26 --track 1.25 go
```

--------------------------------

### Example: List sketches in current project

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-sketches.rst

Lists all sketches in the current project directory. The output includes project path, workshop name, revision, and notes status.

```console
$ workshop sketches
```

--------------------------------

### Launch workshop and create Go source file

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.rst

Launches the workshop and shows a simple Go program that prints 'hello, Workshop'.

```console
$ workshop launch

```

```go
package main

import "fmt"

func main() {
    fmt.Println("hello, Workshop")
}

```

--------------------------------

### Error message format - avoid examples

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the error message format to avoid: starting with a capital letter, having trailing punctuation, or being too generic.

```go
return fmt.Errorf("Cannot connect plugs.") // Starts with capital, has punctuation
return fmt.Errorf("Error") // Not descriptive enough
```

--------------------------------

### How-to guides list

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows how to list how-to guides in navigation and links, dropping the 'How to' prefix and using the infinitive form.

```restructuredtext
How-to guides:

* Debug issues in workshops
* Connect VS Code to a workshop
```

--------------------------------

### Run workshopd directly

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Installs the workshopd binary and runs it directly with the required environment variables and the --create-dirs flag.

```console
$ go install ./cmd/...
$ export WORKSHOP_DATA=~/workshop
$ export WORKSHOP_CACHE=~/workshop-cache
$ export WORKSHOP_DEBUG=1
$ workshopd run --create-dirs

```

--------------------------------

### Avoid Godoc conventions example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the discouraged Godoc comment style: comments do not start with the element name. The comments are generic and do not follow the convention.

```go
// Represents a development environment.
type Workshop struct { ... }

// Creates and starts a workshop.
func Launch(cfg *Config) (*Workshop, error) { ... }
```

--------------------------------

### setup-base: Add SDK bin to PATH

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/build-an-sdk.rst

A minimal setup-base hook that adds the SDK's bin directory to the system PATH by writing a profile script. Runs as root on first install and every refresh. Use /etc/profile.d/ for portability across shells.

```shell
cat <<EOF > /etc/profile.d/<NAME>.sh
export PATH="$SDK/bin:\$PATH"
EOF
```

--------------------------------

### Workshop configuration for dev-volatile

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/fix-workshops/debug-issues.rst

Example workshop configuration named dev-volatile that uses an unstable SDK from the latest/edge channel. This is the setup referenced in the debugging scenario.

```yaml
name: dev-volatile
base: ubuntu@22.04
sdks:
  - name: go
    channel: edge

```

--------------------------------

### Show workshop info to display mount details

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/interfaces/mount-interface.rst

Provides an example of the workshop info command showing mount details for the mount-sdk, including host-source and workshop-target, which demonstrates a mounted interface connection.

```console
$ workshop info ws

  name:     ws
  base:     ubuntu@22.04
  project:  /home/user/workshops/ws
  status:   ready
  notes:    -
  sdks:
    mount-sdk:
      tracking:   latest/edge
      installed:  2022-03-04  (1)
      mounts:
        cache:
          host-source:      .../8584e571/ws/mount/mount-sdk/cache
          workshop-target:  /home/workshop/.local/cache
```

--------------------------------

### Launch the dev workshop

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Launches the dev workshop from the repository root. Requires Workshop and LXD to be installed first.

```console
$ workshop launch dev

```

--------------------------------

### Systemd service unit file for Ollama

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.rst

Service configuration that starts the Ollama server on boot and restarts it on failure. Installed to the user's systemd directory.

```ini
[Unit]
Description=Ollama Service
After=network.target

[Service]
ExecStart=/bin/bash -lc "ollama serve"
Restart=always
RestartSec=3

[Install]
WantedBy=default.target
```

--------------------------------

### Error message format - good examples

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the required error message format: start lowercase, no trailing punctuation, and follow the template "what was attempted: why it went wrong". Proper nouns like "SDK" or "LXD" may start with a capital letter.

```go
// From cmd/workshop/connect.go
return fmt.Errorf("cannot connect plugs and slots across different workshops")

// From cmd/workshop/list.go
return fmt.Errorf(`cannot list: "--project" incompatible with "--global"`)

// From internal/daemon/api_workshops.go
return statusBadRequest("project-id required")
```

--------------------------------

### Console example with command and output

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows the pattern for console examples: a command with the nonselectable `$` prompt followed by indented output. The `console` lexer in `.. code-block::` makes the prompt nonselectable during copy operations.

```restructuredtext
.. code-block:: console

   $ workshop launch dev

     Launching dev...
     Launched dev

```

--------------------------------

### setup-project hook: write UID and install bash aliases

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-sdks/write-runtime-hooks.rst

Runs as the workshop user with the working directory set to /project/. Use for per-project initialization. The hook runs after auto-connect has finished, so mounts and the project directory are visible, and the home directory is writable.

```shell
id -u >"$HOME/.dotfiles-uid"
install -m 0644 -t "$HOME" "$SDK/skel/.bash_aliases"
```

--------------------------------

### Console example with separated output

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows command output formatting: indent output with two spaces and separate it from the command with a blank line.

```restructuredtext
.. code-block:: console

   $ workshop list --global

   PROJECT          WORKSHOP  STATUS   NOTES
   ~/myproject      dev       Running  -
   ~/otherproject   test      Stopped  -

```

--------------------------------

### Example: sdkcraft revisions my-sdk

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-revisions.rst

Lists revisions for the SDK named 'my-sdk'.

```console
$ sdkcraft revisions my-sdk
```

--------------------------------

### Mount plug ros-cache definition

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/sdk-vs-dockerfile.rst

SDK definition snippet defining a mount plug named ros-cache that mounts to /home/workshop/.ros. This avoids manual setup when starting the workshop, as plugs are mounted automatically.

```yaml
plugs:
  ros-cache:
    interface: mount
    workshop-target: /home/workshop/.ros
# ...
```

--------------------------------

### Start the GitHub Runner with workshop exec

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/run-github-actions-locally.rst

Starts the Runner client inside the workshop. Replace `<OWNER>/<REPO>` with the full repository name (e.g., `canonical/workshop`); if omitted, the script tries to detect it from the local repository. For organization-level runners, provide the organization name (e.g., `canonical`). The `--label` option adds a label to distinguish the runner from GitHub-hosted and other self-hosted runners. On first run, it requests authorization using a one-time code.

```console
$ workshop exec ci github-runner --label=workshop <OWNER>[/<REPO>]
```

--------------------------------

### YAML endpoint quoting for tunnel interface

Source: https://github.com/canonical/workshop/blob/main/docs/reference/definition-files/_interfaces/tunnel.rst

Endpoints that start with `[` or `@` must be quoted in YAML. This example shows two separate endpoint values, one for an IPv6 address and one for an abstract socket.

```yaml
endpoint: '[::1]:8080/tcp'
endpoint: '@abstract.sock'
```

--------------------------------

### Initialize a workshop with SDKs

Source: https://github.com/canonical/workshop/blob/main/docs/readme.rst

Create a workshop definition file (.workshop/dev.yaml) from a comma-separated list of SDKs. The command writes the file which can be extended with actions.

```console
workshop init dev --sdks opencode,go/1.26/stable
```

--------------------------------

### Good comment format example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the recommended comment style: complete sentences starting with a capital letter and ending with a period. The comments describe the Workshop struct and validateName function, and include an inline comment for the empty name check.

```go
// Workshop represents a development environment running in a container.
type Workshop struct {
    Name string
    Base string
}

// validateName checks that the workshop name is valid.
func validateName(name string) error {
    // Empty names are not allowed.
    if name == "" {
        return fmt.Errorf("name cannot be empty")
    }
    return nil
}
```

--------------------------------

### Relaunch workshop after removal

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.rst

Relaunches the workshop if it was removed earlier in the guide.

```console
$ workshop launch

```

--------------------------------

### setup-base hook: configure environment

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.rst

This hook runs when the workshop is launched or refreshed, typically used to install system packages and configure the environment. It writes an environment script to /etc/profile.d/ollama.sh.

```shell
cat <<EOF >/etc/profile.d/ollama.sh
export PATH="$SDK/bin:\$PATH"
EOF
```

--------------------------------

### sdk info openvino

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-info.rst

Prints metadata, Store channels, and local installations for the 'openvino' SDK.

```console
$ sdk info openvino
```

--------------------------------

### workshop remount: example

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-remount.rst

Mounts the 'mod-cache' plug of the 'go' SDK in the 'nimble' workshop to '~/new-cache-mount' on the host. The command attempts an atomic mount and falls back to requiring the workshop to be stopped if the source is not an existing empty directory on the same file system.

```console
   $ workshop remount nimble/go:mod-cache ~/new-cache-mount

```

--------------------------------

### Install Workshop extension from terminal

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/connect-vscode.rst

Installs the Workshop extension for VS Code from the terminal. The extension depends on Remote - SSH, which VS Code installs alongside it.

```console
$ code --install-extension canonical.workshop
```

--------------------------------

### Manual defer cleanup for transactional setup

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Alternative to the revert package: manual defer cleanup. The deferred function checks the named return error and unmounts on failure, ensuring cleanup even when later steps fail.

```go
func setupMount(path string) (err error) {
    defer func() {
        if err != nil {
            // Clean up on error
            unmount(path)
        }
    }()
    
    if err := mount(path); err != nil {
        return err
    }
    
    if err := configure(path); err != nil {
        return err // defer will unmount
    }
    
    return nil
}
```

--------------------------------

### Stop and start a workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/use-multiple-workshops.rst

Stops and starts a workshop independently.

```console
$ workshop stop frontend
$ workshop start frontend
```

--------------------------------

### Run built binary and observe output

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.rst

Runs the built binary './main' and shows its output 'hello, Workshop'.

```console
$ ./main

  hello, Workshop

```

--------------------------------

### Error specificity - good example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the recommended pattern for error specificity: check for specific error types like os.IsNotExist and return descriptive errors that preserve context.

```go
if _, err := os.Stat(path); err != nil {
    if os.IsNotExist(err) {
        // Handle file not found specifically
        return fmt.Errorf("configuration file %q not found", path)
    }
    return fmt.Errorf("cannot access configuration file %q: %w", path, err)
}
```

--------------------------------

### Console example with comments

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Shows two forms of comments in commands: full-line comments and inline comments with two spaces before the `#`.

```restructuredtext
.. code-block:: console

   # Full line comment explaining the command
   $ workshop launch dev

   $ workshop exec dev -- echo "test"  # Inline comment with two spaces before #

```

--------------------------------

### Run documentation test suites

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Run the end-to-end test suites for the documentation tutorials and how-to guides.

```console
$ spread tests/docs-tutorial/
$ spread tests/docs-how-to/
```

--------------------------------

### Initialize SDK with sdkcraft init

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.rst

Changes into the ollama directory and runs 'sdkcraft init' to create a template sdkcraft.yaml file.

```console
$ cd ollama/
$ sdkcraft init
```

--------------------------------

### Launch workshop and get hostname

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/run-jetbrains-gateway.rst

Launch the workshop if it isn't already running, then find the workshop hostname from the output of 'workshop info'. Use the hostname from the output when configuring JetBrains Gateway.

```console
$ workshop launch
```

```console
$ workshop info

name:      dev
base:      ubuntu@24.04
project:   ~/my-project
hostname:  dev.my-project.wp
...
```

--------------------------------

### Good type switch example

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the recommended pattern for handling multiple possible types using a type switch with explicit error messages for each case. This provides better error reporting and is the established pattern in the codebase.

```go
switch ro := readOnly.(type) {
case bool:
    return ro, nil
case string:
    parsed, err := strconv.ParseBool(ro)
    if err != nil {
        return false, fmt.Errorf("invalid boolean string %q", ro)
    }
    return parsed, nil
default:
    return false, fmt.Errorf("read-only must be bool or string, got %T", ro)
}
```

--------------------------------

### Run sdkcraft try to build and pack the SDK

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.rst

Run this command in the ollama/ directory to build and pack the SDK into files such as ollama_amd64_ubuntu@24.04.sdk. The output shows the packed files for each supported platform.

```console
$ sdkcraft try

  Packed ollama_amd64_ubuntu@22.04.sdk
  Packed ollama_amd64_ubuntu@24.04.sdk
  ...
```

--------------------------------

### Command usage example

Source: https://github.com/canonical/workshop/blob/main/cmd/internal/doctemplates/command.rst

Shows the command usage as displayed in the console code block. The placeholder {{ .Synopsis }} is replaced with the actual command synopsis when the template is rendered.

```console
$ {{ .Synopsis }}
```

--------------------------------

### workshop init usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Shows the general usage syntax for the workshop init command. Replace <NAME> with the workshop name and optionally provide flags.

```console
$ workshop init <NAME> [flags]
```

--------------------------------

### Install requests package in Jupyter

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.rst

Installs the requests package inside the Jupyter console using the %pip magic command.

```console
In [1]: %pip install requests

```

--------------------------------

### Configure systemd service with snap part (ollama SDK)

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/best-practices.rst

Defines a snap part that dumps the ollama.service file into the build. Used in the setup-project hook to install the service.

```yaml
parts:
  user-service:
    plugin: dump
    source: ollama.service
    source-type: file
```

--------------------------------

### Run workshopd with go tool try

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Builds ./cmd/... into a temporary session directory under try_sessions/, starts workshopd against it, and drops you into a subshell with WORKSHOP_DATA, WORKSHOP_CACHE, WORKSHOP_SOCKET, and PATH pre-configured. Exit the shell to tear the session down. Pass --keep to retain the session directory. Run again from inside the shell to rebuild and restart workshopd in place.

```console
$ go tool try

```

--------------------------------

### Build-time SDK definition (sdkcraft.yaml) for Go SDK

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/sdks/concepts.rst

Example of a build-time definition file (sdkcraft.yaml) for a Go SDK, showing metadata, platform configurations, plugs, and a part that downloads and dumps the Go toolchain. Use this as a template when authoring an SDK for the Workshop platform.

```yaml
name: go
build-base: ubuntu@24.04
title: Go SDK
summary: The Go programming language
description: |
  Go is an open source programming language that enables the production of simple, efficient and reliable software at scale.
version: "1.25.1"
license: LGPL-2.1
platforms:
  amd64:
    build-on: [amd64]
    build-for: [amd64]
  arm64:
    build-on: [amd64]
    build-for: [arm64]
  riscv64:
    build-on: [amd64]
    build-for: [riscv64]

plugs:
  mod-cache:
    interface: mount
    workshop-target: /home/workshop/go/pkg/mod

parts:
  go:
    plugin: dump
    source: https://go.dev/dl/go$CRAFT_PROJECT_VERSION.linux-$CRAFT_ARCH_BUILD_FOR.tar.gz
    source-type: tar
```

--------------------------------

### Example of desired tone and voice

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of the desired tone and voice for Workshop documentation, showing an authoritative but relaxed style.

```text
Workshop is a tool for defining and handling ephemeral development environments.

List your dependencies and components in YAML to define an environment. The key pieces of a definition are SDKs, independent but connectable units of functionality created by software publishers and available on the SDK Store. Workshop simplifies experiments with your environment layout.
```

--------------------------------

### Prerequisites section example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a Prerequisites section in a how-to, placed as a top-level section after the opening paragraph and before the first procedure.

```restructuredtext
Prerequisites
-------------

Before starting, ensure you have these requirements satisfied:

- LXD 6.8 or later running on the host.

- An Ubuntu One account.
```

--------------------------------

### Metadata example: Workshop interface system

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example metadata block from the documentation for a comprehensive explanation of the Workshop interface system.

```restructuredtext
.. meta::
   :description: A comprehensive explanation of the Workshop interface system,
                 detailing how SDKs connect to host system resources through
                 interfaces, and the mechanism of plugs and slots for resource
                 sharing between containers.
```

--------------------------------

### Check mount interface connection with workshop connections --all

Source: https://github.com/canonical/workshop/blob/main/docs/explanation/interfaces/mount-interface.rst

Use this example to verify that the mount interface is connected. The output shows the plug ws/mount-sdk:cache connected to slot :cache with manual notes.

```console
$ workshop connections --all

  INTERFACE  PLUG                SLOT    NOTES
  ...
  mount      ws/mount-sdk:cache  :cache  manual
```

--------------------------------

### Multi-base SDK definition with no parts

Source: https://github.com/canonical/workshop/blob/main/docs/reference/definition-files/sdkcraft-definition.rst

Example SDK definition that supports multiple bases (noble and jammy) without any parts. Each platform maps build-on and build-for to specific Ubuntu versions and architectures.

```yaml
name: multibase
version: "0.1"
summary: Multibase SDK
description: |
  This is my multibase SDK description.
license: GPL-3.0
platforms:
  noble:
    build-on: [ubuntu@24.04:amd64, ubuntu@24.04:arm64]
    build-for: ubuntu@24.04:all
  jammy:
    build-on: [ubuntu@22.04:amd64, ubuntu@22.04:arm64]
    build-for: ubuntu@22.04:all
```

--------------------------------

### Check hostname and Go version in workshop terminal

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/connect-vscode.rst

Run these commands in the integrated terminal inside the workshop to confirm the current directory and that Go is installed. The expected output shows the hostname 'dev' and Go version 'go1.27.1 linux/amd64'.

```console
workshop@dev:/project$ hostname

  dev
workshop@dev:/project$ go version

  go version go1.27.1 linux/amd64
```

--------------------------------

### Usage: sdkcraft init command

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdkcraft-init.rst

Shows the basic command syntax for initializing an SDKcraft project. Use this to see the available options: --name, --profile, and the optional project directory.

```console
$ sdkcraft init [--name NAME] [--profile {simple}] [project_dir]
```

--------------------------------

### Release notes metadata example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example metadata block from release notes, showing the {eval-rst} directive with a description specific to the release.

```markdown
```{eval-rst}
.. meta::
   :description: Release notes for Workshop v0.1.28, highlighting key changes,
                 new features, and bug fixes in this version.
```

# Workshop v0.1.28 release notes
```

--------------------------------

### Use realistic test data for Workshop

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Use realistic data structures that match actual API responses. This example includes multiple fields and nested SDKs to catch edge cases and integration issues that simplified fakes miss.

```go
testWorkshop := Workshop{
    Name:   "dev",
    Base:   "ubuntu@22.04",
    Status: "Ready",
    SDKs: []SDK{
        {Name: "go", Channel: "latest/stable"},
    },
}
```

--------------------------------

### Open shell and list matching devices

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/use-host-devices.rst

Opens a shell in the workshop and lists the matching devices. The output shows the host devices reachable inside the workshop.

```console
$ workshop shell dev
workshop@dev:~$ ls /dev/input/

  event0  event1  mice
```

--------------------------------

### Go program for hello-workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/connect-vscode.rst

A simple HTTP server that responds with the Go runtime version. This is the main program file for the workshop project.

```go
package main

import (
     "fmt"
     "net/http"
     "runtime"
)

func main() {
     http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
             fmt.Fprintf(w, "Hello from %s\n", runtime.Version())
     })
     fmt.Println("Listening on http://localhost:8080")
     if err := http.ListenAndServe(":8080", nil); err != nil {
             fmt.Println(err)
     }
}

```

--------------------------------

### Start Jupyter Console in workshop shell

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-3-sketch-sdks.rst

Activates the Jupyter virtual environment and starts the Jupyter console, providing an interactive environment to experiment with Ollama.

```console
$ workshop shell
workshop@dev:/project$ source /var/lib/workshop/sdk/jupyter/venv/bin/activate
(jupyter-venv) workshop@dev:/project$ jupyter console

  Jupyter console 6.6.3
  ...

```

--------------------------------

### Help string formatting for CLI commands

Source: https://github.com/canonical/workshop/blob/main/docs/coding-style-guide.md

Shows the recommended help string style: single spaces and concise descriptions. Avoid multiple spaces or verbose explanations.

```go
// Good: Single spaces, concise
Short: "Launch a new workshop",
Long: `Launch creates and starts a workshop. The workshop will be based on the configuration in workshop.yaml.`,

// Avoid: Multiple spaces or verbose explanations
Short: "Launch  a  new  workshop",
Long: `This command will launch a new workshop. It will create the workshop based on the configuration...`,
```

--------------------------------

### Good link text example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Good example of link text: descriptive phrase integrated into the sentence, avoiding generic 'click here' or 'see this' text.

```default
See the available installation options in LXD documentation.
```

--------------------------------

### Check Workshop snap version

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/fix-workshops/fix-installation.rst

Check the installed version of the Workshop snap against the latest release on GitHub. The output shows the installed version, revision, and confinement.

```console
$ snap info workshop

  ...
  installed:    0.1.13 (x18) 24MB classic

```

--------------------------------

### Initialize a Git repository and create a workshop definition

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/develop-with-workshops/use-git.rst

Initializes a Git repository and changes into it, then defines a workshop with name 'dev', base image 'ubuntu@22.04', and Go SDK version 1.26.

```console
$ git init original
$ cd original/

```

```yaml
name: dev
base: ubuntu@22.04
sdks:
  - name: go
    channel: 1.26

```

--------------------------------

### En dash usage examples

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Examples of using the en dash (–) to represent ranges or connections between related items. Use this punctuation style in documentation.

```default
pages 10–15
East–West traffic
Ubuntu 22.04–24.04
```

--------------------------------

### sdk info usage

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-info.rst

Shows the command's usage syntax: sdk info <SDK> [flags].

```console
$ sdk info <SDK> [flags]
```

--------------------------------

### Anchor label examples with prefixes

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Examples of anchor labels using the required lowercase-with-underscores format and section type prefixes (tut_, how_, exp_, ref_).

```restructuredtext
.. _tut_get_started:
.. _how_add_actions:
.. _exp_interface_concepts:
.. _ref_workshop_launch:
```

--------------------------------

### workshopctl set-health error example

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshopctl.rst

Example of reporting an error status with a code and a message. Only the message is quoted; the code is not. This command is used by the check-health hook after launch or refresh operations.

```console
$ workshopctl set-health --code=missing-cuda error "CUDA libraries not found"
```

--------------------------------

### sdk info openvino --arch all

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-info.rst

Shows channels for every supported architecture.

```console
$ sdk info openvino --arch all
```

--------------------------------

### Example commit message

Source: https://github.com/canonical/workshop/blob/main/docs/contributing/development.rst

Example commit message following Workshop's capitalization convention. It rarely states the commit type; types are used for branch naming instead.

```none
Ensure correct permissions and ownership for the content mounts

 * Work around an LXD issue regarding empty dirs:
   https://github.com/canonical/lxd/issues/12648

 * Ensure the source directory is owned by the user running a workshop.

Links:
- ...
- ...
```

--------------------------------

### Create workshop with Go and UV SDKs

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-init.rst

Creates a workshop named 'dev' with the Go and UV SDKs. The command creates .workshop/dev.yaml and fails if a workshop with the same name already exists.

```console
$ workshop init dev --sdks go,uv
```

--------------------------------

### Usage: sdk list [flags]

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-list.rst

Shows the command usage for 'sdk list'. Use this to see the available flags.

```console
$ sdk list [flags]
```

--------------------------------

### Workshop definition file (golang)

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/move-projects.rst

Example workshop definition file that defines a workshop named 'golang' based on ubuntu@22.04 with a Go SDK. This is the definition file that is used in the examples on this page.

```yaml
name: golang
base: ubuntu@22.04
sdks:
  - name: go
    channel: 1.26
```

--------------------------------

### Define SDK with try- prefix in workshop metadata

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-4-craft-sdks.rst

Use the try-<NAME> prefix to reference an SDK installed in the try area. No channel is needed; the SDK is installed from the try area when the workshop launches.

```yaml
name: dev
base: ubuntu@24.04
sdks:
  - name: try-ollama
```

--------------------------------

### Launch a workshop

Source: https://github.com/canonical/workshop/blob/main/docs/tutorial/part-1-get-started.rst

Launches the workshop, making it ready for use. The output shows the workshop name and status.

```console
$ workshop launch

  "dev" launched

```

--------------------------------

### Usage: sdk find <QUERY> [flags]

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/sdk-find.rst

Shows the command syntax for 'sdk find'. Use this to see the expected arguments and flags.

```console
$ sdk find <QUERY> [flags]
```

--------------------------------

### Launch workshop in project directory

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/move-projects.rst

Command to launch a workshop in a project directory. This is the initial step before moving or copying the project.

```console
$ workshop launch --project /home/user/old/
```

--------------------------------

### Refresh, stop, remount, and start the workshop

Source: https://github.com/canonical/workshop/blob/main/docs/how-to/customize-workshops/add-mounts.rst

Commands to refresh the workshop, stop the `dev` workshop, remount the `readonly` plug to `~/refdata`, and start the workshop again. Stop the workshop first if `~/refdata/` already holds reference data.

```console
$ workshop refresh
$ workshop stop dev
$ workshop remount dev/uv:readonly ~/refdata
$ workshop start dev
```

--------------------------------

### Run command with env and working directory

Source: https://github.com/canonical/workshop/blob/main/docs/reference/cli/workshop-exec.rst

Runs 'go build -x' in the 'nimble' workshop with the environment variable GO111MODULE=off and the working directory /project.

```console
$ workshop exec --env GO111MODULE=off -w /project nimble -- go build -x
```

--------------------------------

### Warning admonition

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Example of a warning admonition in reStructuredText.

```restructuredtext
.. warning::

   This will permanently delete all workshop data.
```

--------------------------------

### Preferred direct instruction example

Source: https://github.com/canonical/workshop/blob/main/docs/doc-style-guide.md

Preferred phrasing for direct instructions, using imperative mood.

```default
Install Workshop using the --classic option:
```
Tokens:
Raw