# Workshop

> This is the documentation for Workshop, a Canonical tool for defining and
> handling ephemeral development environments that run as containers.
> List your dependencies and components in YAML to define an environment,
> composed of SDKs: independent but connectable units of functionality
> from the SDK Store or project repo. Workshop targets teams who build and
> maintain complex, error-prone workspaces in domains
> such as AI/ML, robotics, IoT, and EdTech.


2026

## Pages

- [**Workshop**](https://ubuntu.com/workshop/docs/index.md): Home page for Workshop documentation, providing links to tutorials, how-to guides, references, and explanations.
- [Page not found](https://ubuntu.com/workshop/docs/404.md): Custom 404 error page that appears when users cannot find a documentation page they were looking for, providing guidance on how to navigate further.
- [How to add actions to your workshop](https://ubuntu.com/workshop/docs/how-to/customize-workshops/add-actions.md): How-to guide on adding actions to workshops, enabling automation and enhanced functionality without modifying SDKs.
- [How to add mounts to a workshop](https://ubuntu.com/workshop/docs/how-to/customize-workshops/add-mounts.md): How-to guide on adding mounts to a workshop with the mount interface, covering host persistence, sharing existing host directories, read-only exposure, and sharing data between SDKs.
- [Workshop and AI agents](https://ubuntu.com/workshop/docs/reference/ai-agents.md): Reference for Workshop's AI-agent integration points, listing the LLM-readable documentation URLs, the Context7 integration, and the use-workshop and sdk-designer agentic skills.
- [Architecture](https://ubuntu.com/workshop/docs/explanation/architecture.md): Workshop architecture documentation, providing access to explanations of system components and runtime behavior that underpin Workshop environments.
- [Design best practices](https://ubuntu.com/workshop/docs/explanation/sdks/best-practices.md): Best practices for crafting SDKs in Workshop, explaining design decisions for system services, parts decomposition, interfaces, environment variables, content delivery, and health checks.
- [How to build an SDK](https://ubuntu.com/workshop/docs/how-to/develop-sdks/build-an-sdk.md): How-to guide for building a Workshop SDK with SDKcraft, covering scaffolding from the canonical/template-sdk repository, defining parts and interfaces, authoring the hooks, and iterating on the SDK locally.
- [Camera interface](https://ubuntu.com/workshop/docs/explanation/interfaces/camera-interface.md): Documentation on the camera interface that enables workshops to access the host system's cameras and video capture devices for hardware testing, device development, and other video-related applications.
- [Camera interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/camera.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [Changes, tasks](https://ubuntu.com/workshop/docs/explanation/workshops/changes-tasks.md): Explanation of changes and tasks in Workshop, detailing how state management operations are planned and executed as changes consisting of ordered tasks.
- [Command-line interfaces](https://ubuntu.com/workshop/docs/reference/cli.md): Overview of command-line interfaces for Workshop, including user and SDK author tools, with links to detailed command references.
- [Workshop Go coding style guide](https://ubuntu.com/workshop/docs/coding-style-guide.md): Workshop Go coding style guide covering error handling, naming conventions, code structure, testing patterns, and architecture principles derived from PR discussions and contribution standards.
- [System components](https://ubuntu.com/workshop/docs/explanation/architecture/components.md): Explanation article on the system architecture and components of Workshop, detailing installation, the workshopd daemon, LXD backend, state management, interface policy, systemd integration, and data architecture with workshop launch processes.
- [Workshop concepts](https://ubuntu.com/workshop/docs/explanation/workshops/concepts.md): Overview of workshop-related concepts, explaining the role of workshops as containers defined by project directories and hosted by LXD for consistent development environments.
- [Interface concepts](https://ubuntu.com/workshop/docs/explanation/interfaces/concepts.md): 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.
- [SDK concepts](https://ubuntu.com/workshop/docs/explanation/sdks/concepts.md): A comprehensive overview of SDK concepts in Workshop, explaining what SDKs are, how they install packages and configure environments, and how they're distributed through an SDK Store with channel-based versioning.
- [How to connect your local VS Code to a workshop](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/connect-vscode.md): How-to guide on connecting a local Visual Studio Code instance to a remote workshop.
- [How to contribute](https://ubuntu.com/workshop/docs/contributing.md): Guide on contributing to the Workshop project, detailing why and how to join the community, including instructions for code contributions, documentation improvements, releases, and testing opportunities.
- [Custom device interface](https://ubuntu.com/workshop/docs/explanation/interfaces/custom-device-interface.md): Documentation on the custom-device interface that enables workshops to access arbitrary host devices belonging to a given subsystem, for hardware testing, device development, and other applications that need access to non-standard devices.
- [Custom device interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/custom-device.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [How to use workshops](https://ubuntu.com/workshop/docs/how-to/customize-workshops.md): How-to guides on daily usage of workshops, including adding actions, forwarding ports, moving projects, and using multiple workshops within the Workshop ecosystem.
- [How to debug issues in workshops](https://ubuntu.com/workshop/docs/how-to/fix-workshops/debug-issues.md): How-to guide on debugging workshop issues, covering tasks like tracing changes, pausing on errors, and managing system-wide warnings.
- [SDK and workshop definition files](https://ubuntu.com/workshop/docs/reference/definition-files.md): Overview of the YAML definition files used by Workshop and SDKcraft, with links to the reference page for each file.
- [Desktop interface](https://ubuntu.com/workshop/docs/explanation/interfaces/desktop-interface.md): Documentation of the desktop interface that provides workshops with secure access to the host system's display (Wayland/X11) for running GUI applications within isolated environments.
- [Desktop interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/desktop.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [How to develop SDKs](https://ubuntu.com/workshop/docs/how-to/develop-sdks.md): How-to guides for building and publishing Workshop SDKs with SDKcraft, covering project layout, hooks, and the SDK Store publish flow.
- [How to develop with workshops](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops.md): How-to guides on usage of workshops with well-known developer tools.
- [Workshop documentation style guide](https://ubuntu.com/workshop/docs/doc-style-guide.md): Workshop documentation style guide covering file naming, structure, semantic line breaks, reStructuredText and Markdown conventions, terminology, and project-specific patterns.
- [Explanation](https://ubuntu.com/workshop/docs/explanation.md): An overview of Workshop's core concepts, explaining how workshops, projects, and SDKs work together to create consistent development environments and help build workflows.
- [How to troubleshoot **Workshop**](https://ubuntu.com/workshop/docs/how-to/fix-workshops/fix-installation.md): How-to guide on troubleshooting Workshop issues, including verifying installation, updating prerequisites, and checking versions.
- [How to fix workshops](https://ubuntu.com/workshop/docs/how-to/fix-workshops.md): How-to guides on fixing workshops, including debugging issues, troubleshooting installations, and purging workshops.
- [How to forward ports with tunneling](https://ubuntu.com/workshop/docs/how-to/customize-workshops/forward-ports.md): How-to guide on forwarding ports with the tunnel interface in Workshop, covering scenarios like exposing services and connecting to remote systems.
- [GPU interface](https://ubuntu.com/workshop/docs/explanation/interfaces/gpu-interface.md): Documentation of the GPU interface that enables workshops to access the host system's GPUs directly, allowing for improved performance of GPU-intensive applications and workloads in isolated environments.
- [GPU interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/gpu.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [How-to guides](https://ubuntu.com/workshop/docs/how-to.md): How-to guides for Workshop, addressing common scenarios and corner cases when using Workshop and SDKcraft.
- [Interfaces](https://ubuntu.com/workshop/docs/explanation/interfaces.md): Workshop interfaces documentation, providing access to explanations of interface concepts and specific interface types used for resource sharing between containers.
- [How to manage Python environments with the uv SDK](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/manage-python-environments.md): How-to guide on using the uv SDK to manage Python projects and virtual environments inside a workshop, including pinning the project venv with UV_PROJECT_ENVIRONMENT.
- [Mount interface](https://ubuntu.com/workshop/docs/explanation/interfaces/mount-interface.md): Documentation of the mount interface that securely exposes file system locations from the host or within the workshop, enabling data persistence and resource sharing between isolated environments.
- [Mount interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/mount.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [How to move projects around](https://ubuntu.com/workshop/docs/how-to/customize-workshops/move-projects.md): How-to guide on moving and copying project directories in Workshop, explaining how workshops react to these operations before and after launch.
- [Multi-workshop patterns](https://ubuntu.com/workshop/docs/explanation/workshops/multi-workshop-patterns.md): Explanation of the two architectural patterns for using multiple workshops, the scenarios each pattern fits, and the boundary between what stays shared and what stays isolated.
- [Get started with workshops](https://ubuntu.com/workshop/docs/tutorial/part-1-get-started.md): Practical introduction to workshops, guiding users through defining, launching, and refreshing workshops, and executing commands in workshops.
- [Work with interfaces](https://ubuntu.com/workshop/docs/tutorial/part-2-work-with-interfaces.md): Tutorial on using interfaces in workshops to interact with the host system and other SDKs.
- [Customize with sketch SDKs](https://ubuntu.com/workshop/docs/tutorial/part-3-sketch-sdks.md): Tutorial on creating experimental SDKs with the 'workshop sketch-sdk' command, enabling quick local SDK experiments without publishing them.
- [Craft SDKs with **SDKcraft**](https://ubuntu.com/workshop/docs/tutorial/part-4-craft-sdks.md): Tutorial on crafting SDKs with SDKcraft, teaching users how to initialize, define, pack, and publish SDKs for sharing and use with the CLI utility.
- [SDK parts](https://ubuntu.com/workshop/docs/explanation/sdks/parts.md): Explanation of SDK parts in Workshop, detailing how they modularize SDKs and manage dependencies through source, build, and staging phases for improved maintenance and updates.
- [Projects](https://ubuntu.com/workshop/docs/explanation/workshops/projects.md): Explanation of projects in Workshop, detailing how directories are initialized as projects containing workshop definitions and managed with commands such as 'workshop launch'.
- [How to publish an SDK](https://ubuntu.com/workshop/docs/how-to/develop-sdks/publish-an-sdk.md): How-to guide for publishing a Workshop SDK to the SDK Store with SDKcraft, covering pack, test, try, register, upload, and release, plus how to consume the published SDK from a workshop definition.
- [How to purge malfunctioning workshops](https://ubuntu.com/workshop/docs/how-to/fix-workshops/purge.md): How-to guide on purging malfunctioning workshops, covering steps to remove containers, metadata, and files thoroughly.
- [Reference](https://ubuntu.com/workshop/docs/reference.md): Workshop reference guides, providing technical background for using Workshop and SDKcraft, including command-line interfaces.
- [Release notes and upgrade instructions](https://ubuntu.com/workshop/docs/release-notes.md): Release notes and upgrade instructions for Workshop and SDKcraft, including new features, bug fixes, and version-specific guidance.
- [How to fix plug conflicts with binding](https://ubuntu.com/workshop/docs/how-to/fix-workshops/resolve-plug-conflicts.md): Step-by-step guide on binding interface plugs in a workshop to resolve resource conflicts between SDKs.
- [How to run GitHub Actions locally](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/run-github-actions-locally.md): How-to guide on running GitHub Actions locally using the github-runner SDK, enabling local testing, debugging, and development of CI/CD workflows.
- [How to use JetBrains Gateway with Workshop](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/run-jetbrains-gateway.md): How-to guide on running JetBrains Gateway with Workshop for remote development.
- [How to run JupyterLab in your browser](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/run-jupyterlab-in-browser.md): How-to guide on running a JupyterLab instance in a workshop and accessing it via a browser.
- [How to run workshops in GitHub Actions](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/run-workshops-in-github-actions.md): How-to guide on launching workshops in GitHub Actions using the launch-workshop action on hosted runners, with support for matrix builds and SDK caching.
- [Runtime behavior](https://ubuntu.com/workshop/docs/explanation/architecture/runtime-behavior.md): Explanation article on the runtime behavior of Workshop, detailing the workshop launch process, data architecture, ZFS storage, and state database management.
- [sdk (CLI)](https://ubuntu.com/workshop/docs/explanation/sdks/sdk-cli.md): Documentation of the sdk CLI, detailing its role in understanding available SDKs and which workshops use them.
- [SDK definition](https://ubuntu.com/workshop/docs/reference/definition-files/sdk-definition.md): Reference for the runtime sdk.yaml definition file. Covers filename conventions, top-level fields, interface attributes, the JSON Schema, and worked examples.
- [How SDKs compare to Dockerfiles](https://ubuntu.com/workshop/docs/explanation/sdks/sdk-vs-dockerfile.md): A comparison between traditional Dockerfiles and Workshop SDKs, explaining how Workshop's approach to development environments offers improved repeatability, persistence, and layering compared to Docker-based solutions.
- [sdk (CLI)](https://ubuntu.com/workshop/docs/reference/cli/sdk.md): Overview of the "sdk" CLI utility, listing available commands and global options for managing SDKs.
- [sdkcraft (CLI)](https://ubuntu.com/workshop/docs/explanation/sdks/sdkcraft-cli.md): Documentation of the sdkcraft CLI, detailing its role as the SDK-author tool for scaffolding, building, testing, and publishing SDKs to the SDK Store.
- [SDKcraft project definition](https://ubuntu.com/workshop/docs/reference/definition-files/sdkcraft-definition.md): Reference for the sdkcraft.yaml build-time definition file. Covers filename conventions, top-level fields, platforms, parts, interface attributes, the JSON Schema, and worked examples.
- [sdkcraft (CLI)](https://ubuntu.com/workshop/docs/reference/cli/sdkcraft.md): Overview of the "sdkcraft" CLI utility, listing available commands and global options for managing SDKcraft projects.
- [SDK internals](https://ubuntu.com/workshop/docs/reference/sdks.md): Reference guide to SDK internals, including source directory structure, parts, plugs, slots, and modularization in Workshop SDKs.
- [SDKs](https://ubuntu.com/workshop/docs/explanation/sdks.md): Workshop SDK documentation, providing access to explanations of SDK concepts, data storage, lifecycle hooks, and comparisons with traditional container approaches.
- [Security policy](https://ubuntu.com/workshop/docs/security.md): This is an overview of security considerations for Workshop and SDKcraft.
- [SSH interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/ssh-agent.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [SSH interface](https://ubuntu.com/workshop/docs/explanation/interfaces/ssh-interface.md): Documentation of the SSH interface that allows workshops to securely use the host's SSH agent, keys, and configuration for accessing private repositories and remote machines from within isolated environments.
- [Tunnel interface](https://ubuntu.com/workshop/docs/explanation/interfaces/tunnel-interface.md): Documentation of the tunnel interface that enables network service sharing between workshops and the host system, supporting TCP, UDP, and Unix domain socket connections for accessing applications across isolation boundaries.
- [Tunnel interface](https://ubuntu.com/workshop/docs/reference/definition-files/_interfaces/tunnel.md): sdk-definition.rst, and sdkcraft-definition.rst.
- [Tutorial](https://ubuntu.com/workshop/docs/tutorial.md): Workshop tutorial, providing a three-stage guide to creating workshops, building SDKs, and publishing them as essential components of the ecosystem.
- [How to use workshops with Git](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/use-git.md): How-to guide on using workshops with Git, covering initialization, repository setup, and best practices for development workflows.
- [How to use multiple workshops in a project](https://ubuntu.com/workshop/docs/how-to/customize-workshops/use-multiple-workshops.md): How-to guide on using multiple workshops in a single project for modular isolation, covering setup, management, sharing in-project SDKs, and cross-workshop networking via the tunnel interface.
- [How to use workshops with AI agents](https://ubuntu.com/workshop/docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.md): How-to guide on using Workshop for parallel agentic coding, demonstrating multiagent workflows with 'claude-code' and 'copilot' SDKs in a shared sandbox environment.
- [Workshop v0.9.0 release notes](https://ubuntu.com/workshop/docs/release-notes/v0.9.0.md): Release notes for Workshop v0.9.0, the first public release under GPL v3, with the workshop init command, a startup firewall check, GPU passthrough via LXD CDI, workshop-agnostic snapshots, Ubuntu 26.04 support, and arm64 snap builds.
- [Workshop and SDKcraft 0.9.1 release notes](https://ubuntu.com/workshop/docs/release-notes/v0.9.1.md): Release notes for Workshop and SDKcraft 0.9.1, covering the custom-device interface, unused SDK snapshot cleanup, clearer exec and refresh output, SDK Store pre-handshake retries, the website field in sdk info, the new sdkcraft revisions command, and ubuntu@26.04 base support.
- [workshop (CLI)](https://ubuntu.com/workshop/docs/explanation/workshops/workshop-cli.md): Documentation of the workshop CLI, detailing its role in managing the lifecycle of workshops and interacting with the workshopd daemon via a REST API.
- [Workshop definition](https://ubuntu.com/workshop/docs/reference/definition-files/workshop-definition.md): Reference for the workshop.yaml definition file. Covers filename conventions, top-level fields, nested structures, interface attributes, the JSON Schema, and worked examples.
- [Workshop status diagrams](https://ubuntu.com/workshop/docs/reference/workshop-status.md): Reference guide on workshop status changes, providing diagrams that explain lifecycle states and transitions caused by various commands.
- [workshop (CLI)](https://ubuntu.com/workshop/docs/reference/cli/workshop.md): Overview of the "workshop" CLI utility, listing available commands and global options for managing Workshop environments.
- [workshopctl (CLI)](https://ubuntu.com/workshop/docs/explanation/sdks/workshopctl-cli.md): Documentation of the workshopctl CLI, detailing its role as the in-workshop helper invoked by SDK hooks to report back to the workshopd daemon.
- [workshopctl (CLI)](https://ubuntu.com/workshop/docs/reference/cli/workshopctl.md): Command reference for 'workshopctl', detailing its use by SDKs for reporting health and invoking subcommands in workshops.
- [Workshop internals](https://ubuntu.com/workshop/docs/reference/workshops.md): Reference guide to Workshop internals, covering container-based environments, SDK layering, and user/session management.
- [Workshops](https://ubuntu.com/workshop/docs/explanation/workshops.md): Workshop explanation documentation, providing access to explanations of core workshop concepts, change tracking, project management, and command-line interface usage.

---

For more comprehensive documentation, see [llms-full.txt](https://ubuntu.com/workshop/docs/llms-full.txt)