Skip to main content

Managing Wormholes

A constellation is a secure area in which you can deploy your applications. You can take comfort in the notion that nothing from the public internet can access your resources unless you choose to allow it. A wormhole is the mechanism by which you allow traffic to enter your constellation from the Internet.

Creating a Wormhole

Creating a wormhole involves clicking the Wormhole+ icon in the tool palette while on the logical view of the constellation canvas. Upon clicking this, you will be presented a dialog like the following:

Add Wormhole
Add Wormhole

There will be two drop-down lists. The first, actor, will draw from a list of all actors currently running in the constellation that are granted the wasmcloud:httpserver capability that are bound to an instance of the HTTP Server - Wormhole provider (note there can be multiples of these on a given canvas if they differ by link name). Clicking Create Wormhole will create the wormhole in the open state. That is, it will be immediately accessible.

Removing and Closing Wormholes

If you delete (remove) a wormhole, it will be forever gone and you will lose the host name associated with it. In the following screenshot from the wormhole details panel, you can see that the host name is silent-glitter-5370:

Wormhole Details
Wormhole Details

Because of this, you will want to be very careful when deleting wormholes, especially if you have already set up your own custom domain pointing to this host. If you want to stop inbound traffic to your constellation, but you want to retain your claim to the host name, you can click the Close Wormhole button. Once closed, for security reasons, a wormhole will reject incoming traffic, pretending as though it doesn't exist to the outside Internet - you don't want people to be able to tell the difference between closed and non-existent wormholes when probing for weaknesses.

Setting a custom Wormhole name

When you create a wormhole, Cosmonic will generate a random human-readable name for it. If you want to set a custom name, you can do so by clicking the Edit Wormhole button in the wormhole details panel. This will bring up a window where you can set the name, provided it isn't already in use by another wormhole and it passes rules for a valid DNS subdomain.

Edit Wormhole
Wormhole Details

With great power comes great responsibility. The creation of custom wormhole names that include deceptive or offensive language is strictly prohibited. Cosmonic reserves the right to remove any wormhole that violates this policy.

Using a custom domain

Cosmonic wormholes support custom domains by using an external CNAME record pointed at a wormhole's A record. When your CNAME is setup, and the wormhole is configured, we are able to provision a certificate for the domain via ACME HTTP

Please follow these steps to setup a custom domain:

  • edit the wormhole and set its name to something meaningful
    • ex: example-test-appname
  • add a CNAME in your DNS provider
    • ex: with a record value of
  • edit the wormhole and enter in the custom domain field and click confirm
Edit Wormhole
Wormhole Details

Validation of the CNAME occurs after you click confirm Please make sure to configure the CNAME before you set the custom domain to avoid delays

To remove a custom domain, simply edit the Wormhole Custom Domain field to be empty and click confirm

Authenticated Wormholes

If you want to require an authorization header to access your wormhole, then you can click the require authentication option. Once you do this, Cosmonic will generate a bearer token on behalf of this wormhole. You can then copy that token to a clipboard and supply it in the HTTP Authorization header to obtain authentication.

Sign up for updates

Make sure to stay abreast of all of the Cosmonic news to be informed when new wormhole features, authentication modes, and content types become available.