Skip to main content

Cosmonic Managed Key-Value Provider

Cosmonic-managed Provider

You will not be able to download or start this provider on hosts running outside of Cosmonic.

While there are a number of available open source key-value providers that you can run on Cosmonic, the easiest path to granting your actors access to a key-value store is by using Cosmonic's built-in provider.

Why use Cosmonic Managed Key-Value?

Managing data can be complicated, expensive, and time-consuming. Cosmonic's included key-value store is hosted on our managed infrastructure and immediately available to compute that's connected to your Cosmonic constellation, making it a simple solution for quickly accessible data.


To run this capability provider, you'll need a Cosmonic account and a Cosmonic managed host. If you don't have an account you can sign up here. Once you log in, if you need a Cosmonic managed host, navigate to the infrastructure view and click Host+. You can add labels if you'd like, but they are not necessary.

Running this Capability Provider

To launch this provider, head to the logic view, click Provider+, and input the following OCI reference URL in the launch provider dialog:

This provider must be launched on a Cosmonic host. In the launch provider dialog, select Find Host and supply the following criteria, which will select the host running in Cosmonic infrastructure:


Example Usage

Once you have your key-value capability provider running in your constellation, you can link it to your application components and perform key-value operations. To try this out on your own, you can use an actor that you've already developed or the key value counter example. We're going to run this actor and two capability providers that implement its two contracts, an HTTP Server and the already-launched Cosmonic managed key-value:

KVCounter on a Cosmonic managed host

Starting an Actor

The OCI reference for this actor is and will populate in the dropdown when you click Actor+. Next, select Find Host and supply the following criteria, which will select the host running in Cosmonic infrastructure:


Starting the HTTP Server Provider (wormhole)

Next, you'll want to start the wormhole version of the HTTP Server provider, as shown in the previous dialog. Make sure you change the OCI reference to Similar to the previous provider start, you're going to want to find a host on which to launch this provider. This provider must be launched on a Cosmonic host. If you specify cosmonic_managed, true as the criteria for finding a host, any of those hosts will be able to run this provider.


At this point, you should have the following running in your constellation:

  • One Cosmonic managed host with:
    • HTTP Server (Wormhole)
    • Key-Value Counter Actor
    • Cosmonic Managed Key-Value

With all of this running, it's time to set link definitions and configure a wormhole.

Using the link definitions section of the user guide as a reference, you will want to create the following link definitions:

  • Key Value Counter -> HTTP Server (Wormhole) provider. No values need to be supplied.
  • Key Value Counter -> Built-in Key-Value (Cosmonic) provider. No values need to be supplied. The only option available is the global field. Setting this field to true indicates that all actors within the same constellation will share the same key space. If you leave this field off or set it to false, each actor (unique by public key) will receive its own private key space.

Creating a Wormhole

Follow the instructions in the user guide 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 Cosmonic managed 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). Add a counter name to the end of the URL like demo. For example, accessing the "quiet sound" wormhole (, we see the JSON output from the counter (your wormhole URL will be different):

{"counter": 22}
Open Beta

During the open beta, your key-value storage for this provider will be limited to 128MB. This provider automatically scales with Cosmonic, so in future releases, it can be upgraded to support broad, distributed replication, automated backups, redundancy, etc.