Skip to main content

Quickstart

The cosmo CLI is your one-stop-shop for all things Cosmonic. It puts at your fingertips the ability to interact with and connect to your constellations. As we progress through the developer preview phase, more and more functionality will be added to cosmo, such as the ability to interact with your account, preferences, and much more.

1. Installing the CLI​

OpenSSL 1.1

cosmo requires an OpenSSL 1.1 compatible version to start hosts on Linux. You can usually use your package manager of choice to install the openssl package, but if that installs version 3 (which is the default on Ubuntu 22.04+), you'll need to follow the steps in this issue to install a 1.1 compatible version. We're looking into removing this requirement in the future.

bash
bash -c "$(curl -fsSL https://cosmonic.sh/install.sh)"
bash
bash -c "$(curl -fsSL https://cosmonic.sh/install.sh)"

2. Hello, XKCD! Running Your First Application on Cosmonic​

After installing cosmo, you're ready to run your first application. Let's start with a simple application that retrieves a random XKCD web comic:

bash
cosmo tutorial xkcd
bash
cosmo tutorial xkcd

The above command will authenticate your local machine and launch the XKCD application on Cosmonic. This application consists of a single actor, which is a stateless, reactive component that represents the smallest unit of compute that you can create. This actor is connected to two capability providers: one to listen on incoming HTTP requests, and another to make outbound HTTP requests to the XKCD API.

After running the tutorial command, check the output for a URL. This is a publicly accessible endpoint that makes an HTTP request to the actor running on Cosmonic. Go ahead, navigate to it in your browser! You should see a random XKCD comic. Refresh the page to get a different one!

You can visualize the application on the Logic View of the Cosmonic UI. You'll see a node on the canvas for your actor, which is connected to the two capability providers. Right now, this is all running on Cosmonic. Now let's turn to local development and see how easy it is to go from an idea to a real application, running anywhere.

3. Making it Your Own​

Prerequisites

Since we'll be editing Rust code, make sure you have Rust installed, and ensure you have a WebAssembly target added to your toolchain. You can add this target with:

bash
rustup target add wasm32-unknown-unknown
bash
rustup target add wasm32-unknown-unknown

Generating a New Actor​

Let's see how easy it is to update an application with new code. First we'll generate a new actor project. There are a few minimal templates built in, but let's start with the code that already exists:

bash
cosmo new actor --git https://github.com/cosmonic/awesome-cosmonic --subfolder xkcdgenerator my-xkcd
bash
cosmo new actor --git https://github.com/cosmonic/awesome-cosmonic --subfolder xkcdgenerator my-xkcd

This command generated a git repository in the my-xkcd directory with everything you need to compile and run your actor. Other than the code itself, the most important file here is wasmcloud.toml. This file contains metadata for your project, including the claims, which are a set of capabilities that your actor may use.

Compiling and Signing an Actor​

Building an actor takes just one command:

bash
cosmo build
bash
cosmo build

This command uses your local toolchain to compile the actor into a WebAssembly module. It then signs your actor. We won't go into detail here on the signing process; just remember that all actors must be signed, and cosmo does this for you. If you're interested, you can read more in the wasmCloud documentation on security.

Launching an Actor Locally​

Once again, launching an actor is a single command:

bash
cosmo launch
bash
cosmo launch

All actors run in a host. cosmo launch runs your actors in a local host (and starts a host for you, if one is not already running).

If you return to the Logic View, you'll see a new actor has appeared in your constellation. It has a similar name to the one that you started with the initial tutorial command. However, you'll notice the new actor has a different icon. The Cosmonic UI provides a visual indicator of whether your components are running on a managed host.

However, from a functional perspective, it doesn't matter whether your components are running on a managed host or not. Cosmonic is designed for distributed applications; whether parts of your application are running on a laptop, in a cloud provider's VM, or on a Raspberry Pi is irrelevant in most cases!

Connecting an Actor to Capability Providers​

You'll also notice that the new actor is not connected to any capability providers. This is because the actor you generated has its own unique identity key, different from the pre-built actor you started with the tutorial command, and links are based on the actor's ID.

To link your new actor to the capability providers, you can simply drag from each of the capability names on the actor to the corresponding provider. A modal will open, allowing you to provide custom configuration, but the default values are fine, so you can just click "Create Link."

Allowing Inbound Traffic​

Your new actor is linked up and ready to go! The only remaining step is to create a new wormhole, which is Cosmonic's fun name for an HTTP ingress point. Starting from the Logic View once again, click the + Wormhole button. This will open a new modal where you select which actor to connect to HTTP requests coming from outside Cosmonic. Select your new actor xkcdgenerator (the one without the space) and click "Create Wormhole."

Select the new node that appears on the canvas, which will open a side panel with details about your new wormhole. From there, click the "Access your Wormhole" button to open a new tab. You should see another XKCD comic! This time, the comics are being generated by your new actor that is running locally.

The Flexibility of Distributed Applications

Notice what you didn't do: start any new capability providers. Your new actor is running locally, but it's connected to the capability providers running on Cosmonic. This isn't unique to actors, either; you can also run capability providers locally, and connect them to actors running anywhere!

Updating an Actor​

Let's return to the new actor. The source code is in src/lib.rs. Open this file and take a moment to familiarize yourself with the logic. The actor implements a single function handle_request. In this function, we generate a random number, issue an HTTP request to the XKCD API, and return an HTML response (which is rendered by your browser).

The random number is generated in a range, representing the list of comic IDs which were valid at the time this template was first written. Since some time has passed, you could increase the upper end of the range to the new maximum comic ID. (At the time of writing, 2779 is the latest comic ID.) Or, you could restrict the range, or eliminate the randomness altogether and always request the same comic! A personal favorite is #1053.

In your editor, change the logic related to selecting a comic. Feel free to change some of the HTML response as well. For example:

rust
let random_num = random_in_range(1053, 1053).await?; // Sample from the best 😉
rust
let random_num = random_in_range(1053, 1053).await?; // Sample from the best 😉
rust
let body = format!(
    r#"
<!DOCTYPE html>
<html>
<head>
    <title>Your Not-So-Random XKCD comic</title>
</head>
<body>
    <h1>A classic: {}</h1>
    <img src="{}"/>
</body>
</html>
    "#,
    comic.title, comic.img
);
rust
let body = format!(
    r#"
<!DOCTYPE html>
<html>
<head>
    <title>Your Not-So-Random XKCD comic</title>
</head>
<body>
    <h1>A classic: {}</h1>
    <img src="{}"/>
</body>
</html>
    "#,
    comic.title, comic.img
);

Once you've updated your actor's code, launch the new version:

bash
cosmo launch
bash
cosmo launch

cosmo will take care of replacing your actor with the updated code. If you refresh the tab connected to your wormhole, you'll see the results of your changes! It's that easy to iterate quickly on your ideas.

Next Steps​

This XKCD application used two capabilities: HTTP Server and HTTP Client. This allowed our app to receive/reply to HTTP requests through a wormhole and query an external API. Notice the lack of boilerplate details in this code: no ports, no TLS certificates, and yet you were able to make a request and receive your response. Cosmonic believes this is the way applications should be built. In other words, Write the Right Code. Let us handle the rest.

To make more dynamic applications, you'll want to explore more capabilities. In the next section, we'll walk through a few applications that include different capabilities. You can also explore the full list of capabilities, or read more about building with Cosmonic.