Networking
TSI, bridge networking, TCP port publishing, DNS, and platform boundaries
Networking
Networking has three modes: default TSI, user-defined bridge, and none. Pick the smallest mode that fits the workload.
Mode Matrix
| Mode | Use when | How it works | Boundary |
|---|---|---|---|
| TSI | The workload needs simple outbound access or host TCP publishing. | Guest socket operations are proxied through the host. | No user-defined peer network. |
| Bridge | Boxes need stable private IPs and peer discovery. | A real guest network interface is attached through a platform backend. | Backend behavior differs by OS. |
| None | The workload should be intentionally offline. | No network setup. | No outbound or inbound connectivity. |
# Default TSI
a3s-box run -d --name web -p 8080:80 nginx:alpine
# Bridge
a3s-box network create backend --subnet 10.89.0.0/24
a3s-box run -d --name api --network backend -p 8080:80 myapi:latest
# No networking
a3s-box run --network none alpine:latest -- truePublished Ports
Supported form:
a3s-box run -d -p 8080:80 nginx:alpine
a3s-box run -d -p 8443:443/tcp nginx:alpine
a3s-box port webUnsupported forms fail during CLI or Compose validation:
- UDP:
8080:80/udp; - host-IP binds:
127.0.0.1:8080:80; - shorthand:
80; - ranges:
8000-8010:80.
Bridge Backends
| Host | Backend | Peer networking | Published TCP ports | Outbound NAT |
|---|---|---|---|---|
| Linux | passt | Supported | Supported through runtime path | Supported |
| macOS | built-in netproxy | Supported | Supported | Unsupported in bridge mode |
| Windows | Native WHPX path | Named-pipe vsock control and Windows port-forward worker where implemented | Bridge networking is not productized yet | Windows CRI is unsupported |
Run a3s-box info to see what the current host reports. On macOS, use default TSI mode when a workload needs outbound internet access.
Network Commands
a3s-box network create backend --subnet 10.89.0.0/24
a3s-box network ls
a3s-box network inspect backend
a3s-box network connect backend stopped-box
a3s-box network disconnect backend stopped-box
a3s-box network rm --force backendnetwork connect and network disconnect configure inactive boxes for the next boot. Live network hot-plug and hot-unplug are not implemented.
DNS and Hosts
For bridge networks, A3S Box writes /etc/hosts entries for the box itself and known peers. CLI --hostname and --add-host HOST:IP are validated before boot and are applied through the same host-file generation path.
Network Policy
The data model has none, strict, and custom isolation modes. Only none is attachable today. strict and custom are rejected because packet filtering is not implemented; rejecting them avoids a false sense of isolation.