Building An Echo Service
Build and run your first wasmCloud actor
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 actors and capability providers. You'll get to build your own actors and providers in upcoming tutorials, but for now let's get familiar with the runtime and tooling.
Starting a host
To start a host, simply run wash up
.
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).
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
- Manual
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
If you manually installed the host from a downloaded release, look in var/log/erlang.log.1
relative to the folder where you extracted the release tar file.
Viewing the wasmCloud dashboard
Open a browser tab to the URL http://localhost:4000. This is the wasmCloud dashboard (or washboard), a GUI that you will use quite often as you learn to build distributed applications in this ecosystem.

By default, wasmCloud hosts connect to port 4000. If this port isn't available, you won't see
the wasmCloud dashboard. If you need to change the port number, you can set the environment variable
WASMCLOUD_DASHBOARD_PORT
to a new number before starting a host.
Querying hosts with wash
Querying for running hosts
To see a list of running hosts, run the following command:
wash ctl get hosts
You'll see output like this:
⢈⠩ Retrieving Hosts ...
Host ID Uptime (seconds)
NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI 711
Querying a host's inventory
Now let's check the host's inventory. Using your host ID (not the one in this guide):
wash ctl get inventory NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI
You'll see output similar to the following (your host ID will be different):
Host Inventory (NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI)
hostcore.os linux
hostcore.osfamily unix
hostcore.arch x86_64
No actors found
No providers found
The start of the output displays a host's labels. By default, this includes the operating system and
architecture the host is running on. These labels are prefixed by hostcore
.
The rest of the inventory includes a list of actors and capability providers. Since we haven't started any actors or providers, these lists are empty.
The terminal output you've seen so far is also reflected in the dashboard. Throughout our guides and tutorials, we may alternate between the wasmCloud dashboard UI and terminal-based CLI. When it comes to managing a host's inventory, everything you can do in one view, you can do in the other.
Running an actor
We'll return to the dashboard UI now. (If you're interested in doing this with wash
, refer to
this page). From the dashboard, click the Start Actor button and choose
the From Registry option. When prompted for an OCI reference URL, enter
wasmcloud.azurecr.io/echo:0.3.8
. For now, choose 1 for the number of replicas:

Click Submit, and after a few seconds, you should have a running actor on your host:

Running a capability provider
For this actor to receive HTTP requests, we need to start the HTTP Server capability provider. Actors are signed WebAssembly modules, and as such they have embedded claims declaring their ability to communicate with capability providers like the HTTP Server. Actors cannot communicate with any capability provider for which they have not been signed.
Let's use wash
to inspect the set of capabilities this actor has:
wash claims inspect wasmcloud.azurecr.io/echo:0.3.8
Echo - Module
Account ACOJJN6WUP4ODD75XEBKKTCCUJJCY5ZKQ56XVKYK4BEJWGVAOOQHZMCW
Module MBCFOPM6JW2APJLXJD3Z5O4CN7CPYJ2B4FTKLJUR5YR5MITIU7HD3WD5
Expires never
Can Be Used immediately
Version 0.3.8 (4)
Call Alias (Not set)
Capabilities
HTTP Server
Logging
Tags
None
To start the HTTP server capability provider, click Start Provider and then select From
Registry. Supply the OCI URL wasmcloud.azurecr.io/httpserver:0.17.0
and leave the link name set
to default
. You should now see this capability provider running, and within 30 seconds it should
report its status as Healthy.

Let's return to wash
now and re-query the host's inventory. Re-run the command wash ctl get
inventory
. You should see something like the following (again, your Host ID will be different):
Host Inventory (NCPGH5CVPO3BAZ5OSQKXYHDKPBT3JXLG5EAOTG7XOXUWJ6AHZCFT57SI)
hostcore.osfamily unix
hostcore.os macos
hostcore.arch aarch64
Actor ID Name Image Reference
MBCFOPM6JW2APJLXJD3Z5O4CN7CPYJ2B4FTKLJUR5YR5MITIU7HD3WD5 Echo wasmcloud.azurecr.io/echo:0.3.8
Provider ID Name Link Name Image Reference
VAG3QITQQ2ODAOWB5TTQSDJ53XK3SHBEIFNK4AYJ5RKAX2UNSCAPHA5M HTTP Server default wasmcloud.azurecr.io/httpserver:0.17.0
Linking actors and capability providers
Since the HTTP server provider hasn't been linked to any actor yet, it hasn't yet opened a port to listen to web requests to forward to the actor. To allow the actor and provider to communicate, they need to be linked.
Go back to the web UI and click Define Link. Select the actor and provider from the dropdown
boxes, as shown below. Leave the Link Name as default, and set the Contract ID to
wasmcloud:httpserver
. For the Values field, you'll need to provide an address including hostname
and port. Enter the following in the Values field:
address=0.0.0.0:8080

Once you see that the link has been added to the dashboard, you are ready to send a request to your actor.
Interacting with your actor
In another terminal window, run the following command:
curl localhost:8080/echo
In response, you should receive your request object (notice the path argument):
{"body":[],"method":"GET","path":"/echo","query_string":""}
Feel free to try out different methods of making a request to your actor, including adding headers or using a different HTTP method, to see different outputs.
Congratulations! You've made it through the first guide to wasmCloud. You should now feel
comfortable exploring the ecosystem, starting and stopping the host runtime, interacting with the
wasmCloud dashboard UI, and interacting with hosts using wash
.
To learn more about actors, providers, and other topics, continue on to the Fundamentals section.