# How to connect your network to sandboxes with WireGuard

Run `runtime networks wireguard create`. Then run `peer add office` and
`wg-quick up`. Your machines can reach every sandbox.

**On Runtime, one WireGuard tunnel joins your office, your VPC or your router
to every sandbox in the account. It costs $5 per 30-day month,
with up to 16 peers included** (pricing checked 25 October 2026,
[network products](/docs/pricing#network-products)). Each sandbox gets an
address in the tunnel's subnet. Your machines reach any port of it there, and
no sandbox port is opened to the internet. With the CLI, the private key is
made on your machine and never leaves it.

## Set it up

```bash no-run
runtime networks wireguard create                                # subnet 10.250.0.0/16 by default
runtime networks wireguard peer add office --route 10.0.0.0/16   # writes runtime.conf
sudo wg-quick up ./runtime.conf
runtime networks wireguard get                                   # each sandbox's address
psql -h 10.250.0.32 app
```

```ts check
import { Runtime } from "withruntime";

const runtime = new Runtime();
await runtime.networks.wireguard.create();
const office = await runtime.networks.wireguard.addPeer({
  name: "office",
  routes: ["10.0.0.0/16"],
});
console.log(office.config); // the wg-quick file, shown once
```

```python check
from withruntime import Runtime

runtime = Runtime()
runtime.networks.wireguard.create()
office = runtime.networks.wireguard.add_peer("office", routes=["10.0.0.0/16"])
print(office["config"])  # the wg-quick file, shown once
```

From the SDKs, a peer added with no `publicKey` gets a key pair that Runtime
generates. `config` holds its private key, and it is shown once. The CLI makes
the pair on your machine instead, and writes it to `runtime.conf`, which only
you can read. MCP agents use `runtime_networks_wireguard` with the actions
`create`, `get` and `add_peer`.

## Which client

Any WireGuard client works with a complete file:

- `wg-quick` on Linux and macOS;
- the WireGuard apps on Windows, macOS, iOS and Android;
- your router, if it supports WireGuard.

To use a key pair you already have, pass its public half with `--public-key` to
`runtime networks wireguard peer add`.

## Options and limits

| What                 | Detail                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------- |
| Price                | $5 per 30-day month, prorated to funded time, 16 peers included           |
| Tunnels              | One per account                                                                         |
| Subnet               | `10.250.0.0/16` by default; choose `/16` to `/24` with `--subnet` at create             |
| `--route`            | Your own ranges behind a peer, for sandboxes to reach your network through it           |
| Protocol             | TCP, in both directions; UDP is not carried through the tunnel                          |
| A peer reaches       | Your own account's sandboxes, on any port except Runtime's relays (10800, 10802, 10853) |
| A peer never reaches | Another account's sandboxes, Runtime's servers, the internet                            |
| Paused sandbox       | Woken by a connection                                                                   |

The gateway runs each account's network in its own user-space network stack.
Nothing a peer sends reaches the server's own network stack
([security](/docs/security#domains-tcp-ports-addresses-and-the-tunnel)).

## Rotate or remove a key

```bash no-run
runtime networks wireguard peer rotate <peerId>   # a new key; the old one stops within seconds
runtime networks wireguard peer rm <peerId>       # removes the peer the same way
```

Connections opened with the old key end when that key stops working. MCP agents
use `runtime_networks_wireguard` with `rotate_peer` and `remove_peer`.

## Mistakes and how Runtime handles them

- **A subnet that clashes with yours.** If your network already uses
  `10.250.0.0/16`, pick another range when you create the tunnel:
  `runtime networks wireguard create --subnet 172.30.0.0/16`.
- **`configReady` is false.** The gateway key was not ready yet, so the file is
  a draft. Keep its private key, add the server key once it is available, and
  follow the CLI's instructions before you bring the tunnel up. Do not add
  another peer just to get the same private key again.
- **Sandboxes cannot reach your servers.** List those ranges with `--route` on
  the peer that sits in front of them.
- **Funding lapses.** An unfunded tunnel stops traffic. It keeps its
  reservation and peers until you delete it. Unpaid time is never billed.
  `funded` and `fundedUntil` show where it stands.
- **An account without credit.** The answer is `payment_required` (402).

## Tunnel, public port or port forward?

A tunnel suits steady, private traffic between your servers and many sandboxes.
Examples are a CI fleet reading an internal package mirror, or an agent's
sandbox writing to a database in your VPC. For one person reaching one sandbox,
[port forwarding](/how-to/port-forward-a-database) needs no setup at all. For
clients on the public internet, [open a TCP port](/how-to/open-a-tcp-port).
To have partners admit your sandboxes by address instead,
[reserve a dedicated IP](/how-to/reserve-a-dedicated-ip).

## Related

- [Private networks](/docs/networking#private-networks) in the networking guide.
- [Network access](/docs/security#network-access).
- [Coding agent sandbox](/use-cases/coding-agent-sandbox).

Facts on this page were checked on 26 October 2026.