Skip to main content

Quickstart: Run Your First Workload

This guide takes you from a freshly installed Cosmonic Desktop to a running, sandboxed workload in a few minutes. If you haven't installed yet, start with the install guide for macOS, Windows, or Linux.

Prefer to learn inside the app?

This written quickstart is the reference path. The same first flight—run a workload, then look inside it—is also guided step-by-step in the app's built-in Academy (under Explore), interactive and offline. Use whichever suits how you like to learn.

1. Launch the app​

Open Cosmonic Desktop. The status bar shows the state of your local wasmCloud host—wait for it to report running.

The Workloads view. The status bar (bottom left) reports the host state.
Seeing "disconnected"?

If the status bar says disconnected, the app can't reach its daemon. See Troubleshooting before continuing.

2. Run a component​

The fastest path is pasting a component reference. Choose Start workload and paste this OCI image reference:

ghcr.io/cosmonic-labs/control-demos/hello-world:0.1.2

Desktop pulls the component, inspects it, and drafts a Workload—a declarative spec describing what to run and which capabilities it needs, inferred from the component's declared interfaces (its WIT world—see the glossary if these terms are new). You could also paste a GitHub or GitLab repository URL; every path ends in the same draft-review step.

The review step: the component's image, inferred capabilities, and network reach — egress denied by default.

3. Review and apply​

Look over the draft before applying. This review step is the heart of the Desktop security model. The spec says exactly what the component will be able to do:

  • The image is digest-pinned: the tag you pasted resolves to an immutable digest, and that digest is what runs.
  • Outbound network access is deny-by-default: the component can only reach hosts the spec explicitly allows.
  • Any secrets appear as references, never values.
  • The Signed column reports the image's cosign signature status. This demo component is unsigned. By default the signature policy is advisory, so it's admitted with a warning; Settings → Security can require verified signatures instead.

Choose Deploy workload. The daemon pulls and verifies the image, then starts the component in its sandbox. The workload's status moves to Running as it reports progress.

4. Call the component​

hello-world serves HTTP. The review step showed its ingress hostname (hello-world.localhost); Desktop's built-in ingress listens on 127.0.0.1:8200 (the default) and routes requests to workloads by hostname, so:

curl http://hello-world.localhost:8200/

You should get a greeting back. (On systems whose resolver doesn't handle .localhost subdomains, such as some Linux distributions without systemd-resolved, send the hostname as a header instead: curl -H 'Host: hello-world.localhost' http://127.0.0.1:8200/.) In the app, expanding the workload's row shows its components, capabilities, version and digest, and deployment history; the ingress launch button opens the same address.

The expanded workload row: components, capabilities, pinned version, and deployment history.

5. Look under the hood​

  • The Logs view streams the daemon's event log, including pulls, verifications, starts, and failures.
  • Your workload is plain YAML on disk (workloads/<namespace>/<name>.yaml under the app's state directory)—the same runtime.wasmcloud.dev/v1alpha1 schema Cosmonic Control runs on Kubernetes. It's git-able and deploys to a cluster unchanged.
  • Because the daemon runs as a per-user service on every platform, the workload keeps running even if you quit the app.

Clean up​

Stop or delete the workload from its detail view. Deleting a workload removes its spec; pulled images stay in the local content-addressed cache for instant reuse.

Next steps​

This is walkthrough 1 of three. The next two build on the host you just started:

  • Walkthrough 2: Sandboxing AI — hand a prompt to a coding agent in Builder and land the result in the same sandbox.
  • Walkthrough 3: Build an AI sandbox from scratch — skip the app and build a Rust component by hand with wash, then see the capability boundary in the binary.

Or branch out:

Last updated on by Eric Gregory