hzel Docs

Overview

Private networks let you connect your containers together over an isolated overlay network. Each container you attach gets a static IP address drawn from the network's CIDR block. Traffic between members stays within the overlay and never reaches the public internet.

Networks are independent of container lifecycle — you can attach and detach containers without restarting them, and the network persists until you explicitly delete it.

How it works

When you create a network, hzel provisions a Linux bridge on the underlying host. Each attached container receives a virtual network interface connected to that bridge and a static IP allocated from the network's CIDR block. Containers on the same network can reach each other directly using those IPs.

The CIDR block you supply must be a private range (RFC 1918) with a prefix length between /16 and /28. See CIDR Notation for a full explanation of how to choose a block.

Creating a network

See PrivateNetwork for the full field reference.

POSThttps://api.hzel.org/api/v1/networks

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie. Automatically skipped for `Authorization: Bearer` requests.

Network states

State	Meaning
`creating`	Bridge is being provisioned on the host
`active`	Network is live and accepting members
`deleting`	Network teardown is in progress
`failed`	A lifecycle action could not be completed

Note

Only networks in the active state can have containers attached or detached.

Managing members

See NetworkMembership for the full field reference.

List members

GEThttps://api.hzel.org/api/v1/networks/{network_id}/members

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Add a container to a network

hzel allocates the next available IP from the network's CIDR block and attaches a virtual interface to the container. The container does not need to be restarted.

POSThttps://api.hzel.org/api/v1/networks/{network_id}/members

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Remove a container from a network

The interface is detached and the IP is released back to the pool.

DELETEhttps://api.hzel.org/api/v1/networks/{network_id}/members/{container_id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Membership states

State	Meaning
`attaching`	Interface is being connected to the container
`active`	Container is connected and reachable at `private_ip`
`detaching`	Interface is being removed
`failed`	The attach or detach operation could not be completed

Network management

List networks

GEThttps://api.hzel.org/api/v1/networks

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Get a network

GEThttps://api.hzel.org/api/v1/networks/{network_id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Rename a network

The name field is a display label only — it does not affect routing or the bridge device name.

PATCHhttps://api.hzel.org/api/v1/networks/{network_id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Delete a network

Warning

Deleting a network detaches all member containers first. Ensure your workloads do not depend on the network's IPs before deleting.

DELETEhttps://api.hzel.org/api/v1/networks/{network_id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

List a container's network memberships

Returns all network memberships for the specified container — which networks it belongs to and what IP address it holds on each.

GEThttps://api.hzel.org/api/v1/containers/{container_id}/networks

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Private Networks