Features

Network Shield and Relay

Limited Access

Network shield and relay is a new feature which is available to enterprise customers. If you would like to try it out now, please reach out to the Unikraft Cloud Discord or send an email to support@unikraft.com.

Dedicated unikraft CLI subcommands for the network shield and relay are coming soon. In the meantime, configure them through the API, which you can invoke with curl or the unikraft api command.

A relay redirects all network traffic to and from a network interface toward another network interface. You can set up a relay VM and configure its interface as the relay for another VM's interface, so that all its traffic transparently passes through the relay.

The network shield

The network shield is an example of a relay: an instance inserted between a microVM and the public internet. It sits directly in the path, as a bump on the wire, so every packet the workload sends or receives goes through it first. Since many instances can specify the same microVM as their relay, many sandboxes can share the same network shield.

sandbox

shell

sandbox

filesystem

sandbox

shell / fs

all traffic

Network shield

A microVM every packet passes through, which filters traffic and injects secrets

API keys · tokens

Public internet

Third-party APIs, package registries

Nothing reaches the internet directly: the shield sits in the path, filters traffic, and adds the credentials the instance never holds.

The shield provides filtering capabilities but also the possibility to inject credentials/secrets for agentic or other use cases. This is useful in sandbox environments, as it means the sandbox won't need unfiltered network access or access to secrets.

Each shield runs as its own microVM. This means each shield:

Can be scaled to zero and woken up when it receives traffic.
Is strongly isolated from the microVMs running the workloads, and also from other network shields.
Is fully flexible and extensible in the capabilities it provides. The image it uses determines its behavior.

A first official network shield image will be available soon.

Relay

To use a relay, reference another interface by name inside a relay object:

unikraft api /v1/instances \
  '{
    "name": "my-relay",
    "network_interfaces": [
      {
        "name": "my-relay-iface"
      }
    ]
  }'

Relay builds on custom network configuration: the relay object is a field of a network_interfaces entry, so the same permission, license, and limitations apply.

The relay object accepts the following fields:

Field	Required	Description
`name`	Yes	The name of the interface to relay traffic through, which must belong to another instance in your account.
`relay_dns`	No	Whether the relay forwards DNS requests, `true` by default, with `false` leaving them to the default DNS server.

Relay notes

All network traffic passes over the relay. Many VMs can share a single relay.
Both ends of a relay have to be interfaces that Unikraft Cloud allocates, meaning entries where you set no ip, mac, or tap_name of your own.
You don't need to enable VM-to-VM communication to use this feature (which you don't want in a sandbox environment).
DNS requests can be either passed to the relay or the default DNS server. This is to simplify setups where security isn't the focus as you don't need to run a DNS server in the relay VM.
The guest acting as a relay VM should have net.ipv4.ip_forward=1 and rp_filter=0 set.

Error handling

Error message	Cause
`Insufficient license. Please make sure your license is valid and includes custom network configurations`	Your account's license doesn't include custom network configuration, which relay is part of.
`Unknown member 'network_interfaces'`	Your account lacks the `net_manager` permission required for this feature.
`Invalid relay '<interface>'. Please make sure the relay exists and does not create a circular dependency`	The interface you named doesn't exist, already relays through another interface, or is itself a custom interface.
`Network interface without an IP address cannot use a relay`	You configured a `relay` on an interface without an `ip`, and the relay datapath keys on the client interface's address.

Limitations

The feature requires the net_manager permission and a license that includes it (see the note at the top of this page).
Creating a template from an instance drops its network configuration, since binding a template to a specific TAP device or IP defeats the purpose of cloning many instances from it.
The create call sets the configuration once, and no PATCH support exists yet.
Both ends of a relay have to be interfaces that Unikraft Cloud allocates, meaning entries where you set no ip, mac, or tap_name of your own.
Neither direction of a relay chain works. An interface that already relays can't serve as a relay, and one serving as a relay for others can't take a relay itself.
Every custom network configuration limitation applies here too, since relay is part of that feature.

Learn more

Custom network configuration: the interface, gateway, and nameserver settings that relay builds on.
Instances: how instances work, from their lifecycle to their configuration.
Sandboxes: run untrusted code in a hardware-isolated microVM.
Unikraft Cloud's REST API reference, in particular the section on instances.

Edit this page

Last modified on October 1, 2026

Custom Network Configuration Annotations