Hello World
A familiar starting example to get you up and running with wasmCloud.
If you have not installed wash
, follow the installation guide first.
In this guide, we'll be taking a tour through some of the most common activities in the wasmCloud
ecosystem like starting and configuring the two main components of wasmCloud: actors and
capability providers. All wasmCloud applications need a host to run on, so let's
use wash
to start one now.
Starting a Host
To start a host, simply run wash up
. The default settings should work well for this tutorial. The host can be killed at any time with CTRL+c
This command does a lot behind the scenes, but most importantly it spins up 3 core processes:
- the wasmCloud host which manages the execution of actors and capability providers
- a NATS server to manage communications between application components
- a wadm process which monitors the lattice and maintains the state of managed deployments
By default, wash
will run the host in interactive mode.
If you'd rather run the host in the background, run wash up --detached
(or wash up -d
, for short).
Generating a New Project
Now that our wasmCloud host is running, let's generate a new actor project. This is where our "Hello World" example begins. If you're running your host in the foreground, just switch to another terminal window to run these commands.
This command generates a new actor project in the ./hello
directory:
wash new actor -t hello hello
This actor is a simple Rust project with a few extra goodies included for wasmCloud. At a high level, the important pieces are:
src/lib.rs
: Where the business logic is implementedwasmcloud.toml
: Actor metadata and capability permissionswadm.yaml
: A declarative manifest for running the full application
We'll take a look at each of these in depth later, but for now let's run the example.
Starting our Application
We'll use wash
and wadm, the wasmCloud application deployment manager, to start this actor, the httpserver capability, and link them together to configure them.
wash app deploy wadm.yaml
wadm
will take care of taking this manifest and scheduling the resources on the host that you launched earlier. You should see output in the host logs when your actor and capability start up, and then you can query it yourself:
$ curl localhost:8080
Hello, world!
Congratulations, you just ran a WebAssembly application in wasmCloud!
How does it work?
When you send your HTTP request to localhost:8080
, that request is received by the HTTP Server capability provider. The HTTP Server capability provider then forwards that request to the actor, which responds with the string "Hello, world!". This loose coupling of capability providers and actors provides flexibility, security, and it lets our actor code be loosely coupled to non-functional requirements. Let's take a look at that code now in src/lib.rs
:
use wasmbus_rpc::actor::prelude::*;
use wasmcloud_interface_httpserver::{HttpRequest, HttpResponse, HttpServer, HttpServerReceiver};
#[derive(Debug, Default, Actor, HealthResponder)]
#[services(Actor, HttpServer)]
struct HelloActor {}
/// Implementation of the HttpServer capability contract
#[async_trait]
impl HttpServer for HelloActor {
async fn handle_request(&self, _ctx: &Context, _req: &HttpRequest) -> RpcResult<HttpResponse> {
Ok(HttpResponse::ok("Hello, World!"))
}
}
This actor is set up to receive requests from the HttpServer
capability, with a single function handle_request
that matches what the capability provider expects. All you need to worry about as an applicaiton developer is what functional logic you want to apply when you receive an HttpRequest
, and what HttpResponse
you want to return. There's no mention of ports, certificates, HTTP libraries, and if those things change this actor will work all the same.
Capabilities are deny by default, and if you take a look in wasmcloud.toml
you'll see the only capability is wasmcloud:httpserver
. This means that this actor can never access files on disk, make network requests of its own, or even access the system time, it's blocked by the wasmCloud runtime.
When you ran wash app deploy wadm.yaml
, wadm
takes the application manifest and schedules the components on hosts according to the scale you specify. This example has a minimal manifest, let's take a look at it:
# Metadata
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: hello
annotations:
version: v0.0.1
description: "wasmCloud Hello World Example"
spec:
components:
# Your actor component, started from the wasmCloud example OCI artifact
- name: hello
type: actor
properties:
image: wasmcloud.azurecr.io/hello:0.1.7
traits:
# One replica of this actor will run
- type: spreadscaler
properties:
replicas: 1
# The link configuration tells the httpserver to listen on 8080
- type: linkdef
properties:
target: httpserver
values:
address: 0.0.0.0:8080
# The httpserver capability provider, started from the official wasmCloud OCI artifact
- name: httpserver
type: capability
properties:
image: wasmcloud.azurecr.io/httpserver:0.17.0
contract: wasmcloud:httpserver
Scaling up 📈
WebAssembly can be easily scaled due to its small size, portability, and wasmtime's ability to efficiently instantiate multiple instances of a single WebAssembly module. We leverage these aspects to make it simple to scale your applications with wasmCloud. Let's scale up our hello world application to 50 replicas by editing wadm.yaml
:
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
name: hello
annotations:
# Make sure to bump the version so wadm knows to update the application
version: v0.0.2
description: "wasmCloud Hello World Example"
spec:
components:
- name: hello
type: actor
properties:
image: wasmcloud.azurecr.io/hello:0.1.7
traits:
- type: spreadscaler
properties:
# Update the scale to 50
replicas: 50
Now your hello application is ready to deploy v0.0.2 with 50 replicas. Just run wash app deploy wadm.yaml
again, and you'll see the logs start flowing in. It's a little easier to visualize this in the wasmCloud dashboard, so let's take a look at that next.
Viewing the wasmCloud dashboard (experimental)
To view the wasmCloud dashboard, you'll have to launch wash
with the option --nats-websocket-port 4001
. This is currently an experimental command because the dashboard is still in rapid development.
Go ahead and CTRL+c
or wash down
to stop your previous host, and then relaunch it with the new option:
wash up --nats-websocket-port 4001
Then, you can launch the wasmCloud dashboard using wash ui --experimental
, which will launch the dashboard on http://localhost:3030.
This is a great way to visualize what is running on your host, even multiple hosts that are connected to the same NATS server.

Log files
If you encounter any problems, the host log files may contain useful error messages, and it's good to know how to find them. The tabs below, organized by how you started the wasmCloud host, show you where to find logs:
- Wash Up
- Docker
By default, logs from wash up
are automatically output to your terminal. If you ran the command
with the --detached
flag, logs can be found in ~/.wash/downloads/wasmcloud.log
Logs from hosts running in Docker, if started with our docker compose, can be found by running
docker logs wasmcloud
Next steps
Congratulations! You've made it through the first guide to wasmCloud. You started your first application and
got familiar with the fundamentals of wash
, wadm
, and the wasmCloud dashboard. You should now feel
comfortable exploring the ecosystem. We recommend proceeding onto the next guide, where you can build your own
application and get into the developer loop.