smolvm sandbox port

Use smolvm sandbox port to share a service running inside a sandbox on localhost, list active forwards, and close them when finished.

smolvm sandbox port lets your host reach a service running inside a sandbox. Use it for dev servers, local APIs, databases, and preview apps.

Synopsis

smolvm sandbox port expose <sandbox> [host-port:]sandbox-port [OPTIONS]
smolvm sandbox port list <sandbox> [OPTIONS]
smolvm sandbox port close <sandbox> host-port:sandbox-port [OPTIONS]

Port forwards bind to 127.0.0.1. They are reachable from your host, not from other machines on your network.

Shared options

--ssh-key · string

Path to an SSH private key when SmolVM needs SSH for the forward.

--ssh-user · string · default: "root"

SSH user when SmolVM needs SSH for the forward.

--comm-channel · string

Control channel for setup calls. Use ssh, vsock, or omit it for auto-selection.

--json · flag

Print a JSON envelope instead of formatted text.

expose

Share a sandbox port on localhost:

smolvm sandbox port expose my-sandbox 8080:3000

Let SmolVM pick the host port:

smolvm sandbox port expose my-sandbox 3000

The mapping format is:

Form	Meaning
8080:3000	Host port 8080 forwards to sandbox port 3000
3000	SmolVM picks a free host port for sandbox port 3000

list

Show active forwards:

smolvm sandbox port list my-sandbox

close

Close a forward:

smolvm sandbox port close my-sandbox 8080:3000

Common workflow

smolvm sandbox shell my-sandbox
# inside the sandbox:
# cd /app && npm run dev -- --host 0.0.0.0

smolvm sandbox port expose my-sandbox 3000:3000

Open http://127.0.0.1:3000 from your host browser.

Transports

SmolVM chooses the best forwarding transport for your host:

• nftables when the host can route directly to the guest.
• ssh_tunnel when a background SSH tunnel is the safest path, such as on macOS.

You do not need to choose the transport yourself.

Related commands

• Port forwarding - Use vm.expose_local(...) from Python
• smolvm sandbox shell - Start the service inside the sandbox
• smolvm sandbox stop - Stop the sandbox and release forwards