Private Networks

​

What are Private Networks?

• Run a client and a server in separate sandboxes, such as an agent and the service it is being evaluated against
• Split a workload into tiers, for example web sandboxes that may reach a db sandbox on port 5432 and nothing else
• Spin up a small cluster for distributed tests without exposing anything to the internet

​

Complete Example

prime sandbox create python:3.11-slim --name web
prime sandbox create python:3.11-slim --name db

from prime_sandboxes import APIClient, SandboxClient

client = SandboxClient(APIClient())

network = client.create_lan_network("demo")
client.add_lan_member(network.id, "<web-sandbox-id>", tags=["web"])
client.add_lan_member(network.id, "<db-sandbox-id>", tags=["db"])

prime sandbox network create demo
prime sandbox network add <network-id> <web-sandbox-id> --tag web
prime sandbox network add <network-id> <db-sandbox-id> --tag db

# Serve HTTP on port 8000 in the db sandbox
prime sandbox run <db-sandbox-id> -- bash -c 'nohup python -m http.server 8000 >/dev/null 2>&1 &'

# Reach it by name from the web sandbox
prime sandbox run <web-sandbox-id> -- python -c "import urllib.request; print(urllib.request.urlopen('http://<db-sandbox-id>.sandbox.internal:8000/').status)"

​

Rules

from prime_sandboxes import LanRule

# web may reach db on 5432 and 6379; nothing else is allowed
client.set_lan_rules(
    network.id,
    [LanRule(from_="tag:web", to="tag:db", ports=[5432, 6379])],
)

# Rules are written FROM->TO[@PORT,...]
prime sandbox network rules <network-id> -r 'tag:web->tag:db@5432,6379'

prime sandbox network rules <network-id> \
  -r 'tag:web->tag:db@5432' \
  -r 'tag:worker->tag:db@5432' \
  -r 'tag:web->tag:worker@8080'

• Rules are directed. tag:web->tag:db lets web connect to db, not the other way around. Replies on an allowed connection flow normally.
• The default is open. A new network starts with the single rule *->*. Replace it to restrict traffic.
• An empty rule list blocks everything. Members stay in the network but cannot connect to each other.

​

Tags

# Add with tags, or replace the tags of an existing member
prime sandbox network add <network-id> <sandbox-id> --tag web --tag frontend

​

Reaching Other Members

curl http://<sandbox-id>.sandbox.internal:8000/
psql -h <sandbox-id>.sandbox.internal -p 5432 -U postgres

• Names resolve to private addresses in 198.18.0.0/15. These addresses are per sandbox and may change, so always connect by name.
• Only TCP is supported between members.
• A sandbox can belong to several networks at once. It can connect to a member of any of them, as each network’s rules allow.

​

Managing Networks

# List networks, with sync status
for n in client.list_lan_networks():
    print(n.id, n.name, n.synced)

# Show rules and members
network = client.get_lan_network(network.id)
for member in network.members:
    print(member.sandbox_id, member.tags, member.synced)

# Remove one sandbox, or delete the whole network
client.remove_lan_member(network.id, "<sandbox-id>")
client.delete_lan_network(network.id)

# List networks
prime sandbox network list

# Show rules and members
prime sandbox network get <network-id>

# Remove one sandbox, or delete the whole network
prime sandbox network remove <network-id> <sandbox-id>
prime sandbox network delete <network-id>

​

Limits

​

Quick Troubleshooting

• “Only running sandboxes can join a network”: wait until the sandbox is RUNNING, then add it.
• “Only VM sandboxes can join a network”: private networks are available for VM sandboxes only.
• “The sandbox and the network must belong to the same team or user”: create the network under the same team as the sandbox, or switch your configured team.
• Name does not resolve: names resolve only inside a sandbox that belongs to a network. Check that prime sandbox network get <network-id> lists the sandbox as a synced member.
• Connection refused or reset: no rule allows that path. Check the direction and ports with prime sandbox network get <network-id>.