Skip to main content

Developing with Cosmonic

Depending on your idea, or your business requirements, you'll make use of even more capabilities to create your application. Check out the Capabilities section to see what's available today.

Building a New Application - Simple Overview

Application development with Cosmonic follows a few key steps:

  1. Generate one or more actors from a template with cosmo new actor
  2. Consider the capabilities that your project needs, and declare them in your wasmcloud.toml files
  3. Write, edit, and test code using language-specific tools
  4. Compile your actors using cosmo build
  5. Run your actor so you can debug it
  6. Launch capability providers and link them to your actor to fulfill capability requirements
  7. Create a wormhole, if your application accepts requests over HTTP
  8. Deploy and validate your actors by following the Deployment guide

Building a New Application - In Depth

Step 1: Creating a Project

Here we use the cosmo new actor ... command to build an empty project from one of the available templates. You'll be prompted for (or you can explicitly supply) a project name and any other required information. The output of a newly generated project is ready to build and deploy.

Step 2: Considering Capabilities

Step 2 above is likely going to be a significant shift from how you develop applications today, but the benefits of greater security and looser coupling to non-functional requirements make it well worth the thought exercise. Though you can select specific vendors at this stage (e.g. PostgreSQL to satisfy a SQL database capability), the capabilities that your project needs are generally tied to requirements, not implementation details. To illustrate this process, consider some examples:

An application that serves a RESTful HTTP API, persists data in a SQL store, and writes occasional debug logsHTTP Server, SQL Database, LoggingHTTP Server, PostgreSQL, and the built-in wasmCloud logging
An application that subscribes to an event stream of messages, storing insights in a lightweight cache for quick lookupPubSub Messaging, KeyValue DatabaseNATS Messaging, Cosmonic Built-In KeyValue or Redis

An advantage of building using wasmCloud is if you're looking for a capability that isn't listed, you can write your own capability provider. If you want to develop your own provider, our team would love to hear about your use case and help out however we can. Drop by our Discord and tell us about it!

Step 3: Write, Edit, and Test Code using Language-specific Tools

The process of changing your code will vary depending on the language and environment you're using. Today, the most robust ecosystem for building WebAssembly targets is Rust, but other languages are rapidly smoothing out their developer experience.

Step 4: Build

Our project templates come with a wasmcloud.toml file, which is used to help cosmo build produce signed modules. By default, we generate files that have an _s suffix on them to indicate a signed module, e.g. echo_s.wasm or kvcounter_s.wasm.

Step 5: Run

All WebAssembly modules require a host to run. Whether hosted and managed by Cosmonic or running on your own infrastructure, you'll need to start your actor inside a wasmCloud host to "run" it. Starting an actor on a local wasmCloud host is as simple as running cosmo launch from within your actor's directory.

To access capabilities, your actor will need to be linked to one or more capability providers.

The actor is your unit of deployment and encapsulates your business logic. Capability providers encapsulate non-functional requirements and expose services to actors. Links establish a connection between actors and providers, which can be (re-)configured at runtime. Actors must be linked to running providers in order to access capabilities.

For instructions on how to start providers and add link definitions, including how to do this with a number of sample providers and actors, take a look at the relevant wasmCloud documentation.

Step 7:Create a wormhole

A Wormhole is an ingress point into your constellation. It exposes a single actor through a special wormhole-aware HTTP server provider on a randomly generated DNS name, like Check out our product tour for how to create a wormhole from the Cosmonic UI

Step 8: Deploy

When you're satisfied that what you've built is ready to deploy, refer to the following page: deploying your application.