# Ports

> The SDK methods that forward host ports to ports inside sandboxes, in TypeScript and Python.

Source: https://useshards.com/docs/reference/sdks/ports/

## sandbox.ports.add

Forward a host port to a port on the sandbox's 127.0.0.1, or change the forward it has.

**TypeScript**

```ts
sandbox.ports.add(hostPort: number, guestPort: number, options?: { public?: boolean }): Promise<Port>
```

**Python**

```python
sandbox.ports.add(host_port, guest_port, *, public=False) -> Port
```

**Examples**

**TypeScript**

```ts
const forward = await sandbox.ports.add(9000, 8000);
console.log(forward.listening, forward.reachableOn);
await sandbox.ports.add(9000, 8000, { public: true });
```

**Python**

```python
forward = sandbox.ports.add(9000, 8000)
print(forward.listening, forward.reachable_on)
sandbox.ports.add(9000, 8000, public=True)
```

**Arguments**

| TypeScript | Python | Description |
| --- | --- | --- |
| `hostPort` | `host_port` | port on the host |
| `guestPort` | `guest_port` | port the program in the sandbox listens on, on 127.0.0.1 |

**Options**

| TypeScript | Python | Description |
| --- | --- | --- |
| `public` | `public` | listen on 0.0.0.0, every interface of the host, not 127.0.0.1 |

A running sandbox takes the forward at once; any other from its next start. The forward survives a stop and a start. To forward ports from the first start, pass `ports` to [`shard.create`](https://useshards.com/docs/reference/sdks/sandboxes/#shardcreate).

Add the same host port again to change its guest port or its visibility. `public` is the only way to listen beyond this host; it opens the port to every network the host is on.

**The result**

A `Port` holds the sandbox ID and name, the host and guest ports, `public`, `address`, `listening`, `error` and the addresses a client reaches it on (`reachableOn`, or `reachable_on` in Python). `listening` is false while the sandbox is not running or the host refuses the port, and `error` says why.

## sandbox.ports.list

List the forwards of a sandbox, in host port order.

**TypeScript**

```ts
sandbox.ports.list(): Promise<Port[]>
```

**Python**

```python
sandbox.ports.list() -> list[Port]
```

**Examples**

**TypeScript**

```ts
for (const port of await sandbox.ports.list()) console.log(port.hostPort, port.guestPort, port.listening);
```

**Python**

```python
for port in sandbox.ports.list():
    print(port.host_port, port.guest_port, port.listening)
```

## sandbox.ports.remove

End a forward and the connections it carries.

**TypeScript**

```ts
sandbox.ports.remove(hostPort: number): Promise<void>
```

**Python**

```python
sandbox.ports.remove(host_port) -> None
```

**Examples**

**TypeScript**

```ts
await sandbox.ports.remove(9000);
```

**Python**

```python
sandbox.ports.remove(9000)
```

## shard.ports

List the forwards of every sandbox, in host port order.

**TypeScript**

```ts
shard.ports(): Promise<Port[]>
```

**Python**

```python
shard.ports() -> list[Port]
```

**Examples**

**TypeScript**

```ts
for (const port of await shard.ports()) console.log(port.sandboxName, port.hostPort);
```

**Python**

```python
for port in shard.ports():
    print(port.sandbox_name, port.host_port)
```

For the whole flow, see [Expose a port of a sandbox](https://useshards.com/docs/essentials/expose-a-port/).