Networking

Every Box has a private IPv4 address and no public one. You reach a Box from your workstation through Cubicle's private network: the cubicle CLI opens a WireGuard tunnel to Gateway, and Gateway forwards your traffic to the Boxes you have access to. Boxes can open connections to the public internet, but nothing on the internet can connect to a Box.

1. On your workstation, the cubicle CLI and its tunnel helper hold a WireGuard tunnel to Gateway over UDP.
2. Gateway answers DNS for cubicle.internal names and checks every packet against your expiring access rules.
3. Allowed traffic reaches the Box's private IPv4 address on any port.

To set this up, see Reach a Box over the private network and SSH into a Box.

Private IPv4 addressesCopy Anchor Link

• Each Box gets one IPv4 address from its Node's subnet. Every Node has its own subnet.
• The Box object's privateIp field holds the address. The Box's Node assigns it when it first takes on the Box, shortly after the Box is created, even if it is created stopped. Until then privateIp is null.
• A Box never moves to another Node, so its address stays the same for its whole life: across stop, start, hibernation and restore.
• The address is released when the Box's deletion completes, and a later Box can get it.
• A Box created from a snapshot is a new Box with its own address.
• Boxes have no public IPv4 address and no IPv6. IPv6 is disabled inside the Box.

To look up a Box's address and DNS name, see Reach a Box over the private network.

The path from your workstationCopy Anchor Link

The private network needs the cubicle CLI with its tunnel helper, on macOS or Linux. Platform requirements lists what the helper needs.

• The CLI registers a WireGuard device for your account, named after the workstation's hostname, and the device gets a tunnel address from Gateway's address range. cubicle devices list shows your devices. Revoking a device with cubicle devices revoke is permanent.
• The helper adds a /32 route for each reachable Box's address and one for Gateway's DNS address. Your default route and other traffic are not changed.
• Connections start from your workstation. A Box can only reply; it cannot open connections to your workstation.

Private DNS namesCopy Anchor Link

Each Box you can reach has a private DNS name, built from the Box's name and its organization's name:

<box>.<org>.cubicle.internal

For example, Box job-1 in organization acme is job-1.acme.cubicle.internal. The name resolves to the Box's privateIp.

• If a Box or organization name is not a valid DNS label (for example, it ends with -), that label becomes box-<boxId> or org-<orgId> instead.
• Only cubicle.internal is sent to Gateway. On Linux the helper sets a systemd-resolved routing domain (~cubicle.internal); on macOS it writes /etc/resolver/cubicle.internal.
• Gateway serves only A records, with a TTL of at most 10 s. It does not resolve other names.
• The answers depend on who asks. Gateway resolves a name only for devices whose access session can reach that Box.
• Private names resolve only on connected workstations. They do not resolve inside Boxes.
• The Box's own hostname is box-<name>, which is not its private DNS name.

Gateway answers DNS only for devices with a live access session. A DNS answer never grants access by itself: Gateway checks every packet separately.

Access sessions and expiryCopy Anchor Link

Access to Boxes over the private network is short-lived and renewed continuously while you are connected. cubicle connect and cubicle ssh open an access session for your device using your sign-in session.

• Each refresh returns the current list of reachable Boxes, so a new grant or a Box that has just started appears within about 10 s.
• Revoking a grant, revoking the device, signing out, revoking the sign-in session and a disabled account all end access, including connections that are already open.
• Stopping, hibernating or deleting a Box removes it from your session.
• A start, stop, hibernation or restore advances the Box's connectionGeneration, and Gateway drops the Box from your session until it runs at the new value. See Generations.
• Access sessions need an interactive sign-in. API keys cannot open them. See Sign in and API keys.

Which Boxes a session can reachCopy Anchor Link

A session reaches every Box, in all of your organizations, that meets all of these conditions:

• You hold an active grant on the Box. The owner or admin role is not enough by itself.
• Your membership in the Box's organization is active and your account is not disabled.
• The Box's desired state is running, it is not waiting for an explicit start after a host reboot, its Node is healthy and the Box reports running at its current generation. Every Box whose ssh.ready is true meets this.

An SSH key is not needed for the private network. See Organizations and access for how grants work.

SSH and host-key pinningCopy Anchor Link

SSH runs over the private network to port 22 on the Box's private address. It needs a grant, an ssh-ed25519 public key added to your account and a Box that is ready.

• Cubicle generates each Box's SSH host key when it provisions the Box, and the Cubicle API publishes it. cubicle ssh and cubicle ssh-config fetch the key from the API and pin it per Box ID with StrictHostKeyChecking yes, so ssh never asks you to trust a key and never silently accepts a new one. Host-key checking is never turned off. What the CLI writes lists the files and the Host block.
• You log in as your own guest account.
• The guest SSH server accepts key logins only: no passwords and no root login. Agent forwarding, X11 forwarding and remote forwarding are off. Local forwarding works only to the Box's own localhost, which is enough for editors such as VS Code Remote SSH.

Treat a changed key for the same Box as a security event, and find out why before you accept it. SSH troubleshooting has the fix for each message.

Outbound traffic from a BoxCopy Anchor Link

The blocked private and reserved ranges are 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.168.0.0/16, multicast (224.0.0.0/4) and 240.0.0.0/4.

Inbound traffic to a BoxCopy Anchor Link

• Boxes have no public IP address and no public ports. The only network path to a Box is through Gateway, from a workstation with an access session that can reach the Box.
• Over the private network, any IPv4 protocol and port works: SSH, HTTP, databases, UDP and ICMP.
• A service must listen on the Box's network interface (for example 0.0.0.0), not only on 127.0.0.1. Use SSH local forwarding for services that listen only on localhost.
• Private DNS names have no HTTPS certificates.
• TCP port 5900 on a Box's address reaches the Box's console display (VNC), not a service in the Box. See Use the desktop console.

SSH, the private network or the exec APICopy Anchor Link

See Commands and operations for how exec works and its limits.

RelatedCopy Anchor Link