> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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]
```

<Warning>
  Port forwards bind to `127.0.0.1`. They are reachable from your host, not from other machines on your network.
</Warning>

## Shared options

<ParamField path="--ssh-key" type="string">
  Path to an SSH private key when SmolVM needs SSH for the forward.
</ParamField>

<ParamField path="--ssh-user" type="string" default="root">
  SSH user when SmolVM needs SSH for the forward.
</ParamField>

<ParamField path="--comm-channel" type="string">
  Control channel for setup calls. Use `ssh`, `vsock`, or omit it for auto-selection.
</ParamField>

<ParamField path="--json" type="flag">
  Print a JSON envelope instead of formatted text.
</ParamField>

## expose

Share a sandbox port on localhost:

```bash theme={null}
smolvm sandbox port expose my-sandbox 8080:3000
```

Let SmolVM pick the host port:

```bash theme={null}
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:

```bash theme={null}
smolvm sandbox port list my-sandbox
```

## close

Close a forward:

```bash theme={null}
smolvm sandbox port close my-sandbox 8080:3000
```

## Common workflow

```bash theme={null}
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](/smolvm/features/port-forwarding) - Use `vm.expose_local(...)` from Python
* [`smolvm sandbox shell`](/smolvm/cli/shell) - Start the service inside the sandbox
* [`smolvm sandbox stop`](/smolvm/cli/stop) - Stop the sandbox and release forwards