Copy page

Features

Custom Network Configuration

By default, Unikraft Cloud gives every instance a single network interface, allocated from the platform's address and TAP device pool. Custom network configuration lets you take control of this setup: attach up to four interfaces, supply your own IP addresses and TAP devices, and override the gateway and nameserver.

This is the building block for private networking between your instances.

How it works

You describe an instance's networking when you create it, through three optional fields:

• network_interfaces: a list of one to four interfaces to attach.
• gateway: the default gateway to configure inside the guest.
• nameserver: the DNS resolver to configure inside the guest.

The first interface in the list is the primary interface. It has a special role:

• The private_ip field reported for the instance always comes from the primary interface.
• The proxy forwards incoming traffic to the IP of the primary interface.
• The controller ignores any port announcements from the guest that aren't for the primary interface's IP.

Leaving out network_interfaces is the same as requesting a single pool-allocated interface, so "network_interfaces": [{}] and omitting the field entirely behave identically.

Creating an instance with custom interfaces

Add a network_interfaces array to your POST /instances request:

Each entry in network_interfaces accepts the following fields:

Field	Required	Description
name	No	The interface name. If omitted, Unikraft Cloud generates one as <instance-name>-ethX, falling back to eth-<suffix> when the instance name is too long.
ip	No	The interface IP address in CIDR notation. Provide it together with tap_name to bring your own interface.
tap_name	No	The TAP device to attach the interface to (15 characters or less). Provide it together with ip.
autoconfig	No	Whether the guest configures the interface itself. Defaults to true.
relay	No	An object that routes all traffic through another interface. See Relay.

You either specify both ip and tap_name, or neither. When you omit them, Unikraft Cloud picks an interface from the platform's TAP device pool. The ip and tap_name you supply must not come from that pool.

The top-level gateway and nameserver fields override the values configured inside the guest. If you omit them, Unikraft Cloud derives them from the last address in the IP network of the first pool-allocated interface, or, if there is none, the primary interface.

Like other object names, an interface name is global to your account, not local to the instance. This lets you reference one instance's interface from another.

Autoconfiguration

autoconfig is independent of which TAP device an interface uses and defaults to true. When enabled, the guest configures the interface for you. Disable it to leave the interface untouched, so your app or image can set up networking on its own.

Network Shield and Relay

The network shield feature provides the ability to transparently insert a “shield” between a microVM and the public Internet. 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 will not need unfiltered network access or access to secrets. The shield relies on a relay feature that redirects all network traffic to and from a network interface toward another network interface. This allows for setting up a gateway/proxy VM and configure its interface as the relay for another VM's interface.

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

The relay object accepts the following fields:

Field	Required	Description
name	Yes	The name of the interface to relay traffic through. This interface must belong to another instance in your account.
relay_dns	No	Whether the relay forwards DNS requests. Set to false to let the default DNS server handle them instead. Defaults to true.

Relay notes

• All network traffic passes over the relay. Many VMs can share a single relay.

• This feature supports managed interfaces with custom TAP devices.

• 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.
Network interface must specify an IP address when a TAP device is provided and vice versa	You set only one of ip and tap_name. Provide both or neither.
Network interface IP address cannot be from the platform's address pool	The ip overlaps the platform's managed address pool. Use an address outside it.
Network interface TAP device cannot be from the platform's device pool	The tap_name refers to a platform-managed TAP device. Use one of your own.
Unknown member 'network_interfaces'	Your account lacks the net_manager permission required for this feature.

Limitations

• An instance can have at most four network interfaces.
• 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.
• You currently can't branch or checkpoint an instance with more than one interface.
• The create call sets the configuration once; no PATCH support exists yet.

Learn more

• Instances: how instances work, including their lifecycle and configuration.
• Branching and Checkpoints: create independent copies and reusable restore points of running instances.
• Instance templates: reusable images that you clone into new instances.
• Unikraft Cloud's REST API reference, in particular the section on instances.