Networking

JavaScript examples use @beamcloud/beam-js 1.1.0 or later. Configure the SDK before running them.

Stable application URLs

Run a service on 0.0.0.0 and publish its port:

beam vm exec --detach devbox -- python3 -m http.server 8000 --bind 0.0.0.0
beam vm expose devbox 8000 --public
beam vm ports devbox

Each published port has a stable subdomain URL. Your application’s /, root-relative assets, redirects, and WebSockets use that origin without a VM path prefix. Always use the URL returned by Beam instead of constructing a hostname yourself.

Python
JavaScript

from beam import VM

with VM.connect("devbox") as vm:
    print(vm.expose(8000, protected=False))
    print(vm.get_url(8000))

const vm = await VM.connect("devbox");
console.log(await vm.exposePort(8000, { protected: false }));
console.log(await vm.getUrl(8000));

get_url() only retrieves an already published URL; it does not expose a private port. Removing a published route does not stop the service:

beam vm unexpose devbox 8000

URLs stay the same after stop/start or pause/resume. A fork or restored VM gets its own URLs. A URL cannot serve traffic while the VM is asleep unless automatic resume is enabled.

Persistent IPv6

When allocated, the VM’s public IPv6 address appears in beam vm new and beam vm get NAME. Print only the address with beam vm ip NAME. In Python, vm.public_ipv6 reads the resolved VM metadata without another request; it is None if no address has been allocated. The address survives stop/start and pause/resume. Published TCP ports use the same guest port number. From an IPv6-capable network, connect to a public application port or SSH directly:

beam vm ip devbox
ssh -6 -i ~/.beam/ssh/vm_ed25519 -p 2222 root@"$(beam vm ip devbox)"
beam vm expose devbox 8000 --public
curl -g "http://[$(beam vm ip devbox)]:8000/"

SSH requires the private key matching the VM’s configured public key. beam vm ssh devbox uses the authenticated tunnel and also works from IPv4-only networks. The IPv6 address does not bypass port protection: protected HTTP ports still require the VM traffic token header. Use subdomain browser links below for terminal, desktop, and protected web apps; browser sessions cannot authenticate a raw IPv6 URL. This inbound address is not a fixed outbound source IP.

Protect a published port

New VMs protect the browser terminal (7681) and enabled desktop (8080) by default. Other published ports are public unless protected explicitly:

beam vm new private-desktop --desktop
beam vm expose devbox 8000 --protected

In Python, use ports and protected_ports to protect application ports at creation, or call expose(port, protected=True) later. Terminal and desktop protection needs no extra configuration:

Python
JavaScript

from beam import VM

vm = VM(
    "private-desktop",
    desktop=True,
).create()
vm.close()

const vm = await VM.create({
  name: "private-desktop",
  desktop: true,
});
await vm.close();

Use beam vm new NAME --public-port 7681 or Python VM(public_ports=[7681]) to create a public terminal. Change protection on an existing terminal:

beam vm expose --protected devbox 7681
beam vm expose --public devbox 7681

Python vm.expose(7681, protected=True) and JavaScript vm.exposePort(7681, { protected: true }) also toggle protection. Use 8080 for an enabled desktop. Existing VM specifications are not rewritten; protect older VMs with the commands above. System ports cannot be unexposed or bound, and SSH port 2222 cannot be published or toggled.

Browser access

beam vm desktop NAME, beam vm terminal NAME, and beam vm open NAME PORT generate an expiring entry URL automatically when their port is protected. Opening it exchanges the session credential for a Secure, HTTP-only cookie scoped to that port’s host, then redirects to the stable URL with the credential removed. Open any published HTTP application, or print its usable link:

beam vm expose devbox 8000 --protected
beam vm open devbox 8000
beam vm open devbox 8000 --url

Creation, get, expose, and ports also display usable links for protected ports; ports distinguishes public, protected, tunnel-only, and SSH access. beam vm expose devbox 8000 --protected --url prints only the usable link. JSON output keeps stable metadata URLs without embedding temporary credentials; mint a link separately with beam vm access-url devbox 8000 --ttl 600. Generate an entry URL from an SDK:

Python
JavaScript

from beam import VM

with VM.get("devbox") as vm:
    print(vm.access_url(8000, ttl=600))

const vm = await VM.get("devbox");
console.log(await vm.accessUrl(8000, { ttl: 600 }));

Session TTLs are 1–3600 seconds; the default is 600 (10 minutes), including CLI-generated links. Anyone holding a link can access that port until expiry, so treat it as a credential. If a stable URL reports VM traffic token required, use beam vm open NAME PORT for a fresh link. Rotating the traffic token revokes browser sessions. Through MCP, use vm_access_url, which requires the beam:credentials scope.

Programmatic access

For HTTP clients, use the VM traffic token in X-Beam-VM-Token. This token is distinct from your workspace API token:

url=$(beam vm ports devbox --json | python3 -c \
  'import json, sys; print(json.load(sys.stdin)["8000"])')
token=$(beam vm access-token devbox)
curl -H "X-Beam-VM-Token: $token" "$url"
unset token

Rotate it to revoke the old token and browser sessions:

beam vm access-token devbox --rotate

In Python, use vm.traffic_access_token and vm.rotate_access_token(). The gateway removes the traffic token header and its browser session cookie before proxying to the application. To avoid handling traffic tokens in a local client, use port forwarding.

JavaScript HTTP clients

const vm = await VM.get("devbox");
const url = await vm.exposePort(8000, { protected: true });
const token = await vm.getAccessToken();
const response = await fetch(url, { headers: { "X-Beam-VM-Token": token } });
console.log(await response.text());
await vm.rotateAccessToken();

Private TCP forwarding

Keep a database or other TCP service private and connect through localhost:

beam vm port-forward devbox 15432:5432
# In another terminal:
psql -h 127.0.0.1 -p 15432 -U postgres

The service must already be running in the VM. Configure its application credentials separately. The forwarding listener binds to 127.0.0.1; the command keeps running until you stop it. Equivalent syntax is beam vm port-forward devbox 5432 --local-port 15432. Port forwarding binds an unpublished port for authenticated tunnels without creating a public HTTP URL. SSH uses the same private transport. In Python, vm.bind(5432) makes a port available to authenticated tunnels without publishing it. The low-level beam vm tunnel NAME PORT command bridges a tunnel through stdin/stdout, for tooling integrations; use ssh or port-forward for normal interactive use.

JavaScript TCP streams

const vm = await VM.connect("devbox");
const forward = await vm.portForward(5432, { localPort: 15432 });
console.log(forward.host, forward.port);
// Connect your database client to localhost:15432, then:
await forward.close();

const stream = await vm.tunnel(5432); // Node.js Duplex byte stream
// Use the stream in your TCP client, then:
stream.close();
await vm.close();

Port forwarding and raw streams reconnect using the same resumable private transport. Closing their handles, or vm.close(), releases local listeners and connections.

Outbound network controls

Block outbound traffic or allow only specific hostnames, wildcard domains, IPs, or CIDRs:

beam vm network devbox --block
beam vm network devbox --allow api.openai.com --allow '*.pypi.org'
beam vm network devbox --open

Allowlists accept up to 64 entries, including bare IPv4/IPv6 addresses and CIDRs. A bare address means one host (/32 for IPv4, /128 for IPv6). *.example.com matches subdomains, excluding example.com itself. Hostname rules contain no scheme, path, or port. Hostname rules match TLS SNI on port 443 or the HTTP Host header on port 80. Other TCP ports and protocols need an IP or CIDR rule. The proxy rejects private, loopback, and link-local destinations, including explicit IP/CIDR targets; an allowlist does not create private-network access. Under an allowlist, UDP and ICMP are blocked except DNS to the configured resolver. Rules persist across restarts. Updates close existing connections and take effect without restarting the VM. Do not combine block_network=True with an explicit allowlist.

Python
JavaScript

from beam import VM

with VM.get("devbox") as vm:
    vm.update_network_permissions(block_network=True)
    vm.update_network_permissions(block_network=False, allow_list=["api.openai.com"])
    vm.update_network_permissions(block_network=False, allow_list=[])

const vm = await VM.get("devbox");
await vm.updateNetworkPermissions(true);
await vm.updateNetworkPermissions(false, ["api.openai.com"]);
await vm.updateNetworkPermissions(false, []);

Use --block-network or repeat --allow-network HOST_OR_CIDR at creation. With brokered secrets, blocking allows only their approved credential hosts; an explicit allowlist must cover those hosts with hostname rules and is never widened by a secret. IP/CIDR entries alone do not cover credential hosts. With the default open policy, host rules restrict credential substitution without closing other outbound access. Proxied TCP connections originate from the worker, including connections to CIDR targets. Use the worker’s source IP in downstream access rules. Guest egress rules apply to downloads and API calls, but not to image builds. Egress restrictions do not protect inbound URLs. Configure published-port protection independently.

Start Here

Virtual Machines

Sandboxes

Inference

Building Blocks

Container Images

Data and Storage

Scaling

Operations

Run in Your Cloud

Advanced Topics

Resources

Security

Stable application URLs

Persistent IPv6

Protect a published port

Browser access

Programmatic access

JavaScript HTTP clients

Private TCP forwarding

JavaScript TCP streams

Outbound network controls

​Stable application URLs

​Persistent IPv6

​Protect a published port

​Browser access

​Programmatic access

​JavaScript HTTP clients

​Private TCP forwarding

​JavaScript TCP streams

​Outbound network controls

Stable application URLs

Persistent IPv6

Protect a published port

Browser access

Programmatic access

JavaScript HTTP clients

Private TCP forwarding

JavaScript TCP streams

Outbound network controls