# 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`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#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:

   ```bash
   div sandbox tunnel $SB 3000
   ```

   ```text
   Forwarding sb-4c1e9a:3000 to port 3000 on this machine.
   Press Ctrl-C to stop.
   ```

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

   ```bash
   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:

```bash
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`:

   ```bash
   div sandbox tunnel $SB --exit
   ```

   ```text
   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:

   ```bash
   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:

```bash
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](https://docs.divergentlabs.xyz/sandboxes/mcp.md) 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`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#tunnel).