Develop with the Rust Workshop SDK on Ubuntu¶
This tutorial provides guidance on using the Rust Workshop SDK for development environments on Ubuntu with the Workshop tool. It explains how the SDK manages Rust toolchains for your project and shows how to create a “Hello, world!” program, then goes in-depth with an example that builds a web service and exposes it to your host machine.
For instructions on how to install Workshop and related tooling, see the dedicated guide on how to Get started with workshops. There is no need to install Rust or related tooling directly, as they are installed through the SDK.
The Rust Workshop SDK¶
The Rust ecosystem has a single, canonical Workshop SDK: the rust SDK, which automates the installation and configuration of rustup, Rust’s official toolchain installer.
Where other ecosystems provide separate SDKs for each build tool, the Rust SDK bundles the whole standard toolchain, so one SDK is all a Rust project needs:
Tool |
Description |
|---|---|
|
Build system and package manager |
|
The Rust compiler |
|
Linter that catches common mistakes |
|
Code formatter |
|
Language server for IDE support |
The SDK itself does not pin a compiler version. Instead, it defers to rustup, which selects a toolchain using the following precedence:
A
rust-toolchain.tomlorrust-toolchainfile in your project directory, if present. See the rustup documentation for details.Your personal
rustup defaultselection.The
stabletoolchain.
Dependency caches are stored on the host and survive workshop refreshes, while installed toolchains live inside the workshop container. See the SDK reference section at the end of this tutorial for the details.
Getting started with the Rust Workshop SDK¶
Before using the SDK, install Workshop and its prerequisite, LXD. For more details, see the Workshop getting-started tutorial.
dev@ubuntu:~$ dev@ubuntu:~$ Before initializing a workshop, search the SDK Store to confirm that the SDK exists and get information about the publisher and the available versions.
Confirm/search for available SDKs:
dev@ubuntu:~$NAME VERSION PUBLISHER SUMMARY rust 1.99.1 Canonical** The Rust toolchain installer
Inspect SDK release information:
dev@ubuntu:~$name: rust publisher: Canonical✓ license: Apache-2.0 OR MIT website: https://github.com/canonical/rust-sdk This SDK provides rustup and the Rust toolchain for Rust development. Toolchains and Cargo configuration are persisted on the host across workshop updates. Automatically detects project toolchain requirements via rust-toolchain.toml. CHANNELS CHANNEL VERSION BUILD BASE REV SIZE latest/stable 1.99.1 2026-10-16 ubuntu@26.04 50 4.75MB ubuntu@24.04 49 4.75MB ubuntu@22.04 51 4.78MB latest/candidate ↑ latest/beta ↑ latest/edge ↑
The rust SDK is published by Canonical and tracks a single channel, latest/stable, with builds for the Ubuntu 22.04, 24.04, and 26.04 bases. The CHANNELS table in the sdk info rust output lists the supported bases for your machine.
Note
The output you see depends on the version of the SDK available at the time you run these commands. When a newer release is published, the version number, build date, and revision shown above differ. The CHANNELS table may also list a different set of Ubuntu bases, since it reflects the builds available for your machine.
Creating a Rust workshop¶
Let’s create a “Hello, world!” program and build it with tools from the rust workshop SDK.
Create a project directory for your work. Everything you handle with your workshop goes here: your Rust code, the workshop definition, and so on.
dev@ubuntu:~$dev@ubuntu:~$Initialize the applications workshop definition with the
rustSDK:dev@ubuntu:~/hello-workshop$This command writes the definition to the
.workshop/rust-example.yamlfile with therustSDK pinned to thelatest/stablechannel:.workshop/rust-example.yaml¶name: rust-example base: ubuntu@24.04 sdks: - name: rust channel: latest/stable
Note
When the project directory contains a single workshop definition, you can omit the workshop name from every
workshopcommand that accepts one:workshop launchis equivalent toworkshop launch rust-example. The examples in this tutorial use this shorter form from here on. If your project defines multiple workshops, name them explicitly in the commands to disambiguate.To get the workshop ready for use, launch it and confirm the runtime information matches the definition file:
Prepare workshop after initialization:
dev@ubuntu:~/hello-workshop$"rust-example" launched
This prepares the workshop by automatically pulling and installing the defined SDKs, after which it starts the workshop container.
View information about the workshop:
dev@ubuntu:~/hello-workshop$name: rust-example base: ubuntu@24.04 project: ~/hello-workshop hostname: rust-example.hello-workshop.wp status: ready runtime: lxd-container notes: – sdks: system: installed: (2) rust: tracking: latest/stable installed: 1.99.1 2026-10-16 (49) mounts: cargo-registry: host-source: …/e5faec78/rust-example/mount/rust/cargo-registry workshop-target: /home/workshop/.cargo/registryThe
rustSDK installs rustup and the defaultstabletoolchain inside the workshop, alongside a mount that caches downloaded dependencies on the host between workshop updates. For more information, refer toworkshop info.
Note
To stop the workshop environment from running, use
workshop stop. To then make the workshop ready for use again, start it with theworkshop startcommand.Initialize a Cargo package at the root of the project directory, from within the workshop:
dev@ubuntu:~/hello-workshop$The project directory is mounted as
/projectinside the workshop, so files created on either side (the host or the workshop) appear in both.Cargo generates a package with a
Cargo.tomlmanifest and asrc/main.rsfile that already contains a “Hello, world!” program:src/main.rs¶fn main() { println!("Hello, world!"); }
Build and run the program from within the workshop:
dev@ubuntu:~/hello-workshop$Compiling hello-workshop v0.1.0 (/project) Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s Running `target/debug/hello-workshop` Hello, world!
You should see “Hello, world!” printed in your terminal — and the best part is where it came from. Everything happened inside the workshop container: the toolchain installed by the SDK did the scaffolding, compiling, and running, and your host machine does not need Rust at all.
Managing your Rust toolchain¶
Rust projects often need to control exactly which Rust version they build with: a project may require an older toolchain for compatibility, or you may want nightly features for development. The rust SDK manages this through rustup, giving you two complementary mechanisms.
Pinning a toolchain for the project
Rust’s mechanism for signaling a project’s toolchain requirement is to write the configuration into a rust-toolchain.toml file in the project directory, called the toolchain file.
For example, to pin your project to Rust 1.85.0, create a rust-toolchain.toml file with the following content:
rust-toolchain.toml¶[toolchain]
channel = "1.85.0"
The Rust Workshop SDK listens for this file. Rust commands run in the project directory automatically pick up the pinned toolchain: rustup selects the pinned version and installs it on first use.
Confirm that the workshop uses the pinned toolchain:
dev@ubuntu:~/hello-workshop$ rustc 1.85.0 (4d91de4e4 2025-02-17)
Note
The toolchain file takes precedence over your personal rustup settings. Even if you have selected a different default toolchain, commands run in the project directory use the version pinned in rust-toolchain.toml. Commit the file to your repository, so that every contributor builds the project with the same Rust version.
To stop using the pinned version, remove the file to fall back to the default toolchain.
Selecting a toolchain with rustup
To pick a toolchain version without a project file, use rustup from within the workshop:
dev@ubuntu:~/hello-workshop$ info: using existing install for nightly-x86_64-unknown-linux-gnu
info: default toolchain set to nightly-x86_64-unknown-linux-gnu
nightly-x86_64-unknown-linux-gnu unchanged - rustc 1.101.0-nightly (1a2c4797e 2026-10-21)
Your selection is stored inside the workshop container, so it survives restarts. To confirm this, stop and start the workshop, then check the toolchain again:
dev@ubuntu:~/hello-workshop$ "rust-example" stopped
dev@ubuntu:~/hello-workshop$ "rust-example" started
dev@ubuntu:~/hello-workshop$ rustc 1.101.0-nightly (1a2c4797e 2026-10-21)
The workshop reports the nightly toolchain even after the restart, demonstrating that your selection persisted. To switch back to the stable toolchain:
dev@ubuntu:~/hello-workshop$ info: using existing install for stable-x86_64-unknown-linux-gnu
info: default toolchain set to stable-x86_64-unknown-linux-gnu
stable-x86_64-unknown-linux-gnu unchanged - rustc 1.99.1 (58cf8f9c3 2026-10-13)
Note
Refreshing the workshop re-runs the SDK setup, which resets the default toolchain back to stable and removes any toolchains installed since the last setup. Downloaded dependencies, however, persist across refreshes through the SDK’s cargo-registry mount, so builds pick up where they left off.
Daily workflow with actions¶
Typing the full workshop exec command for every build soon gets tedious. Workshop actions let you name the commands you run often and invoke them as targets of workshop run: workshop run build runs the build action. To list the actions of a workshop, use workshop actions.
Add an actions section to the workshop definition:
.workshop/rust-example.yaml¶name: rust-example
base: ubuntu@24.04
sdks:
- name: rust
channel: latest/stable
actions:
build: cargo build "$@"
test: cargo test "$@"
lint: cargo clippy "$@"
doc: cargo doc "$@"
Each action is a Bash command, and the "$@" expansion forwards every argument supplied after the action name into the command. For instance, workshop run build --release becomes cargo build --release inside the workshop.
Run the actions:
dev@ubuntu:~/hello-workshop$ dev@ubuntu:~/hello-workshop$ Note
Actions are parsed on every workshop run, so there is no need to refresh the workshop after editing them. In non-interactive scripts, where workshop run cannot infer whether its argument names a workshop or an action, use the explicit workshop run -- build form instead.
The same pattern works for any command you run often; see How to add actions to your workshop for more ideas.
Advanced example: expose a Rust web API to your host¶
So far, everything has run inside the workshop. In this section, you build a web service with the axum web framework and expose it to your host machine with a tunnel interface, so you can open it in a browser on the host.
Prerequisites
Workshop and LXD, installed as described in the Workshop getting-started tutorial.
The
hello-workshopproject directory from the previous sections.
Procedure
Add the web framework dependencies to your package:
dev@ubuntu:~/hello-workshop$dev@ubuntu:~/hello-workshop$dev@ubuntu:~/hello-workshop$Cargo resolves the latest compatible versions and records them in the
Cargo.tomlmanifest.Replace the stub
src/main.rsprogram with a small web service:src/main.rs¶use axum::{routing::get, Json, Router}; async fn health() -> Json<serde_json::Value> { Json(serde_json::json!({ "status": "ok" })) } #[tokio::main] async fn main() { let app = Router::new() .route("/", get(|| async { "Hello from a Rust workshop!" })) .route("/health", get(health)); let listener = tokio::net::TcpListener::bind("0.0.0.0:8080") .await .unwrap(); axum::serve(listener, app).await.unwrap(); }
Extend the
.workshop/rust-example.yamlconfiguration to include a slot and plug pair that exposes the application over thelocalhost:8080endpoint, and astartaction to manage the application:.workshop/rust-example.yaml¶name: rust-example base: ubuntu@24.04 sdks: - name: rust channel: latest/stable slots: webapp: interface: tunnel endpoint: localhost:8080 - name: system plugs: webapp: interface: tunnel endpoint: localhost:8080 actions: build: cargo build "$@" test: cargo test "$@" lint: cargo clippy "$@" doc: cargo doc "$@" start: cargo run "$@"
Because the workshop runs in an isolated container, a service listening inside it is not reachable from your host by default. Workshop connects the two sides through interfaces: a slot offers a resource, and a plug consumes it. The tunnel interface forwards network traffic from one endpoint to another.
In our example, we first define a slot for the
rustSDK, which provides the capability to expose a desired network endpoint through the tunnel interface. We then define a tunnel plug that consumes the capability provided by the Rust slot. Since the plug is defined for thesystemSDK, this routes the application endpoint to the host endpoint and allows us to access the application from the host.Refresh the workshop to apply the new interfaces, and confirm the tunnel is in place:
Refresh the environment:
dev@ubuntu:~/hello-workshop$"rust-example" refreshed
View information about the workshop:
dev@ubuntu:~/hello-workshop$name: rust-example base: ubuntu@24.04 project: ~/hello-workshop hostname: rust-example.hello-workshop.wp status: ready runtime: lxd-container notes: – sdks: system: installed: (2) tunnels: webapp: from: 127.0.0.1:8080/tcp to: 127.0.0.1:8080/tcp rust: tracking: latest/stable installed: 1.99.1 2026-10-16 (49) mounts: cargo-registry: host-source: …/e5faec78/rust-example/mount/rust/cargo-registry workshop-target: /home/workshop/.cargo/registryThe output now includes the
webapptunnel, forwardinglocalhost:8080on the host tolocalhost:8080inside the workshop. You can also inspect interface connections with theworkshop connectionscommand:dev@ubuntu:~/hello-workshop$INTERFACE PLUG SLOT NOTES mount rust-example/rust:cargo-registry rust-example/system:mount - tunnel rust-example/system:webapp rust-example/rust:webapp -
Start the application using the new action:
dev@ubuntu:~/hello-workshop$The command keeps running while the server serves requests. Since we have exposed the application through the configured slot/plug pairing, we can then see the application in any browser on the host machine at the
http://localhost:8080endpoint.To verify from the command line instead, run the following on the host:
dev@ubuntu:~/hello-workshop${"status":"ok"}This confirms that the application is running correctly, and is accessible from your host. When you are done, stop the server by pressing Ctrl+C.
SDK reference¶
The rust SDK is published by Canonical and installs rustup together with the standard Rust toolchain. This section documents the interfaces the SDK defines.
Plugs (resources this SDK consumes)¶
cargo-registry¶
Interface:
mountWorkshop target:
/home/workshop/.cargo/registryPurpose: Persists downloaded crate sources and registry caches on the host between workshop updates.
Installed toolchains and rustup configuration live inside the workshop container, under /home/workshop/.rustup. They survive stopping and starting the workshop, while a refresh re-runs the SDK setup and returns the toolchain state to the SDK defaults.
Slots (resources this SDK provides)¶
This SDK doesn’t define any slots out of the box. As shown in the advanced example, you can declare custom slots in your workshop definition to expose services, such as web applications, from the workshop to the host.
For more information¶
The source code for the Rust SDK for Workshop is publicly available on GitHub: rust-sdk.