Skip to main content

External Redis

In this example, we are going to connect an actor to a publicly accessible Redis Database through a key-value provider (specifically the kvredis provider). The actor will then become publicly accessible itself through the Cosmonic-hosted HTTP Server

This example will use a free Redis Cloud instance, though you can use any service that exposes a public address for the database.

Why use Hosted Redis?

One benefit to Cosmonic is that there is no prescription as to where you host the pieces of your application. Perhaps you have an existing Redis instance that you wish to make use of, or perhaps you want other services/applications to be able to access it. This example will allow you to do that.


Accessing Redis

As mentioned, this example uses a free Redis Cloud instance. If you already have a Redis instance, be sure that you have the connection details available. If not, sign up for an account and provision an instance. We used the free tier in the US-East-1 AWS Region, though you can select something closer to you if preferred.

Starting a Host

Actors and Providers need a host to run on. You can start a host on your own infrastructure by using the cosmo CLI, though in this example we will be using a Cosmonic-managed Host. Visit the infrastructure view and if you don't see any hosts, click the Host button to launch one.

New Host Button


Glossary Recap

As a recap, providers are modules that provide capabilities that can be used in actors. For more about this concept, visit the Capability Driven Development page.

Starting the Redis KV Capability Provider

To start this capability provider, click the Provider button on the logic view of your constellation. You will see a modal dialog that looks similar to this:

Launch Provider Dialog
launch provider

Change the OCI Reference to the URL to

Select the host and then click Launch Provider.

Starting the HTTP Server Provider

Start a new instance of the "HTTP Server (Wormhole)" by following the same steps as above, except use as the OCI Reference.

Using the Providers

We're going to use an example actor that has already been made to work with the HTTP Server and Key Value capability contracts: kvcounter.

Starting an Actor

Next up, let's launch the kvcounter actor. From the logic view, click the Actor button:

New Actor Button

You will be presented with a modal like the one below. Change the OCI Reference to, select a host, and launch the actor.

Launch Actor Dialog
launch actor

After launching the actor, you'll notice that it presents two capabilities.

The two capabilities are:

  • wasmcloud:httpserver
  • wasmcloud:keyvalue

Let's link both of these to our providers.

Click and drag from the wasmcloud:httpserver on the actor to the same one on the provider (this dragging works both ways, i.e. you can drag from provider to actor also). This link doesn't need any link values, so just click the Create Link button.

For the second link, click and drag from wasmcloud:keyvalue on the actor to the provider (or vice versa). This one will need a link value. The kvredis provider needs to know the connection string for the Redis database. A connection string for Redis is structured like so:


// e.g.

In the Link Values down the bottom, set the key and value as follows, exchanging <your connection string \> for the one specific to your database:

  • Key: URL
  • Value: <your connection string\>

Click the Create Link button.

Creating a wormhole

Follow the instructions to create a new wormhole. The only option for the target actor should be the key value counter actor. This actor shows up in the list of possibilities specifically because it has a link definition bound to the HTTP Server (wormhole) provider. Actors will not appear as possible wormhole targets without that link.


Now your constellation should contain the following:

  • A key-value counter actor
  • An HTTP Server (wormhole) provider
  • A Redis key-value provider
  • An open, unauthenticated wormhole

At this point you can use the Access your wormhole link from the wormhole detail panel (click the wormhole in your constellation's logic view). In the response, you will see the JSON output from the counter:

{"counter": 1}

Refreshing will increase the count, as the value is being stored in the Redis database. That's it!