Private networks

Linux boxes get a second, private network card (eth1). Use it to let your boxes talk to each other, and to let a box reach your databases, caches and apps without exposing them to the internet.

Boxes talking to each other

Boxes on the same network reach each other directly, on any port, with no setup:

• Boxes in the same isolated group share that group’s network.
• Boxes that aren’t in a group (or are in a shared group) share the workspace network.
• Boxes in different groups, or in different workspaces, can’t reach each other.

Each box can be reached by name: its label in lower case with dashes (a box called “Linux Box 1” is linux-box-1), or zd-<id>, which always works (use it when two boxes have the same label). For example: ping linux-box-2, ssh dev@linux-box-2, curl http://linux-box-2:3000.

The box’s private address and network are shown in its Overview tab, under Private network.

A box joins its network, or moves to a new one after you change its group, at its next start. Stop and start it.

Connecting a box to a database, cache or app

dev-box

running

Ubuntu 24.04

eth1 · private

db

running

Postgres

open

A box linked to Postgres gets DATABASE_URL in /etc/zc-links.env.

Draw a link from the box to the node on the canvas, as you would from an app. The node must be in the same group or network as the box. Then click Deploy.

• The box gets the node’s connection variables, the same names an app would get (for example DATABASE_URL), in /etc/zc-links.env. New login shells load them. In a shell that is already open, run . /etc/zc-links.env.
• Programs already running in the box don’t see new variables: restart them.
• The box’s Overview tab lists each link under Connections with its port and state:
  • after Deploy: the link is drawn but not deployed yet.
  • opening on the host…: it is being set up; this takes a few seconds.
  • open: ready.

Example, from the box:

. /etc/zc-links.env
psql "$DATABASE_URL" -c 'select 1'

What to know

• One way: the box connects to the node. The node can’t open connections to the box.
• TCP only. Nodes without a server of their own (static sites, cron jobs) can’t be linked.
• Box to box needs no link. Boxes in the same group already reach each other, so a box-to-box link is refused.
• Limits: up to 20 box links per workspace, about 61 boxes per network, 200 open connections per link, and 50 new connections per second per box.
• The private network doesn’t reach the internet; the box’s normal network (eth0) does.
• If a node is stopped or asleep, connections to it fail until it runs again.

Troubleshooting

What you see	What to do
No private address on the box	Stop and start the box.
ping linux-box-2 fails with “unknown host”	Stop and start both boxes so their name lists update. Or use zd-<id>.
“different networks” when linking	Move the box and the node into the same group first.
DATABASE_URL is empty	Run . /etc/zc-links.env, or open a new shell. Check that the link shows open.
Connection refused through the link	Check that the node is running (not stopped or asleep).
“already has 20 box links”	Remove a box link you don’t use.