divergent/docs
Sandboxes

Reach your machine from a sandbox

How to make a port on your machine available inside a sandbox, and how to send a sandbox's internet traffic out through your machine.

This guide shows how to use div sandbox tunnel to:

  • make a server on your machine, such as a dev server or database, available inside a sandbox;
  • send the sandbox’s internet traffic through your machine, for sites that block datacenter IP addresses.

To go the other way and reach a port in the sandbox from your machine, use div sandbox forward.

A tunnel needs ssh on your machine. macOS and Linux include it.

Make a port on your machine available in the sandbox

  1. Start the tunnel and leave it running:

    div sandbox tunnel $SB 3000
    Forwarding sb-4c1e9a:3000 to port 3000 on this machine.
Press Ctrl-C to stop.

  2. In the sandbox, connect to localhost:3000:

    div sandbox exec $SB -- curl -s http://localhost:3000/health

  3. Press Ctrl-C to close the tunnel.

If you want the service on a different port in the sandbox, write the sandbox’s port first and your machine’s port second. This makes the Postgres on your port 15432 available on the sandbox’s 5432:

div sandbox tunnel $SB 5432:15432

If you want several ports, list them all in one command: div sandbox tunnel $SB 3000 5432:15432.

Only the ports you name are reachable from the sandbox. In the sandbox, they listen on 127.0.0.1 only, so other sandboxes and the internet cannot reach them.

Send the sandbox’s traffic through your machine

Use --exit only when a site blocks the sandbox, shows it a challenge, or answers it differently than it answers you. Every connection then goes through your machine, so all of the sandbox’s traffic, including npm install, pip install and git clone, is limited to your connection’s speed.

  1. Start the tunnel with --exit:

    div sandbox tunnel $SB --exit
    Sending sb-4c1e9a's internet traffic through this machine.
Press Ctrl-C to stop.

  2. Check the address sites see. It is your machine’s public address:

    div sandbox exec $SB -- curl -s https://ifconfig.me

  3. Do the work that needs your address. Programs in the sandbox need no proxy settings. curl, npm, pip, git, Node’s fetch and the desktop’s Chromium all use the tunnel.

  4. Press Ctrl-C when the sandbox is done with that site. The sandbox’s traffic goes out directly again within a few seconds.

If you need both, combine them: div sandbox tunnel $SB 3000 --exit.

If you download something large, such as a dataset or a container image, do it without --exit.

You are responsible for traffic that leaves from your address, as you would be for commands you run on your own machine.

What --exit reaches

  • Public addresses only. The sandbox cannot reach your machine or your local network through the tunnel. These are refused, including names that resolve to them:
    • loopback addresses;
    • private addresses: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16;
    • carrier-grade NAT, 100.64.0.0/10, which includes Tailscale addresses;
    • link-local addresses, and the IPv6 equivalents of all of these;
    • port 25.
  • TCP only. UDP does not work through --exit, except for DNS lookups. Browsers fall back from QUIC to TCP. Game servers and WebRTC media do not work.
  • DNS through your machine. Sites that answer by region answer as they would for you.
  • One at a time. A sandbox accepts one --exit tunnel at a time. You can open other tunnels with ports alongside it.

Keep a tunnel running for an agent

An agent on your machine can start the tunnel in the background and keep working:

div sandbox tunnel $SB 3000 --exit > /tmp/tunnel.log 2>&1 &
div sandbox exec $SB -- 'cd app && BASE_URL=http://localhost:3000 npm run e2e'

There is no MCP tool for tunnels. An agent that uses the MCP tools runs div sandbox tunnel in its shell.

If the tunnel drops

  • A tunnel that was connected reconnects on its own, for example after your laptop sleeps or your network changes. It prints a line saying it is reconnecting.
  • If the sandbox stops, the tunnel waits and reconnects when the sandbox is resumed.
  • If the sandbox is deleted, the tunnel exits with code 1.
  • While the tunnel is down, a job in the sandbox keeps running, and its traffic goes out directly.

If the tunnel fails to start

A tunnel that fails on its first attempt exits with code 255 and does not retry. The usual cause is a port that is already in use in the sandbox.

  • If a program in the sandbox already listens on the port, map your port to a different sandbox port with <port>:<local port>.
  • If you just closed a tunnel to the same sandbox, wait up to a minute and try again.
  • If another --exit tunnel to the sandbox is open, close it first.

For every argument and flag, see div sandbox tunnel.

esc