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

# Firewalls

> Control inbound traffic to an instance with ingress rules

> [!NOTE]
>
> This feature is in [public preview](https://docs.sfcompute.com/preview/roadmap.md#feature-states).

A firewall is a set of rules controlling inbound traffic to an [instance](https://docs.sfcompute.com/preview/instances.md).
Firewalls are scoped to a [workspace](https://docs.sfcompute.com/preview/workspaces.md).

## Default firewall

Every workspace has a built-in `default` firewall with 2 ingress rules.

* Allow SSH (TCP port 22) from anywhere
* Allow ICMP (ping) from anywhere

SF Compute manages the `default` firewall. You cannot modify or delete it. Password authentication
is disabled on all SF Compute base images, so open SSH is safe by default. Only key holders can
connect.

## How firewalls apply

Firewall rules control traffic between instances and the public internet. Instances in the same
subnet communicate freely on all ports. Instances in different subnets are isolated and cannot
communicate.

Firewalls only apply to instances with a [public IP](https://docs.sfcompute.com/preview/networking/ip-addresses.md) (created with
`--public-ipv4`) and cannot be attached to an instance without one. The API requires the `firewall`
field whenever `enable_public_ipv4` is `true` and rejects the request with 422 when it is omitted.

The CLI fills it in for you. If you run `sf instances create --public-ipv4` interactively without
`--firewall`, it prompts you to pick a firewall. Otherwise, it uses the workspace's `default`
firewall.

## Creating a firewall

Create a firewall from a TOML file that defines the rules.

```bash theme={null}
sf firewalls create --name web --file firewall.toml
```

### Rule format

Each rule specifies a direction, protocol, port (or port range), and source CIDR (Classless
Inter-Domain Routing). The API accepts only `ingress` rules and rejects `egress`, which is reserved
for future use. Firewalls do not filter outbound traffic. The protocol is `tcp`, `udp`, or `icmp`;
ICMP rules take no port.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

This creates a firewall that allows SSH and port 8080 from anywhere.

Source CIDRs must be publicly routable. The API rejects private, reserved, and other non-public
ranges (for example `10.0.0.0/8`, `192.168.0.0/16`). The wildcard `0.0.0.0/0` (allow from anywhere)
is the only exception.

### Restricting access

Restrict SSH to a specific network.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "8.8.8.0/24"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8080"
source = "0.0.0.0/0"
```

### Port ranges

Allow a range of ports.

```toml theme={null}
[[rules]]
direction = "ingress"
protocol = "tcp"
port = "22"
source = "0.0.0.0/0"

[[rules]]
direction = "ingress"
protocol = "tcp"
port = "8000-8999"
source = "0.0.0.0/0"
```

### Create via the API

To create a firewall via the API, send a `POST` request to `/preview/v2/firewalls`.

```json theme={null}
{
  "workspace": "sfc:workspace:acme:production",
  "name": "web",
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" },
    { "direction": "ingress", "protocol": "tcp", "port": "8080", "source": "0.0.0.0/0" }
  ]
}
```

## Attaching a firewall to an instance

Specify the firewall when creating an instance.

```bash theme={null}
sf instances create \
  --name worker-1 \
  --image sfc:image:sfcompute:public:ubuntu-24.04-cuda-13.2 \
  --cloud-init ./startup.sh \
  --public-ipv4 \
  --firewall web
```

## Replacing the firewall on an instance

Replace the attached firewall on an existing instance. The instance must have been created with
`--public-ipv4`. The new rules take effect without a reboot.

```bash theme={null}
sf instances set worker-1 --firewall restricted
```

You can replace the firewall but not detach it.

## Listing firewalls

List the firewalls in the active workspace.

```bash theme={null}
sf firewalls list
```

```text theme={null}
NAME         RULES
default      2
web          2
restricted   2
```

## Getting firewall details

Fetch a firewall by name.

```bash theme={null}
sf firewalls get web
```

Add `--toml` to output the rule set as TOML, which round-trips with `sf firewalls set`.

```bash theme={null}
sf firewalls get web --toml > firewall.toml
```

## Updating a firewall

Replace a firewall's rule set from a TOML file. The replacement is atomic.

```bash theme={null}
sf firewalls set web --file firewall.toml
```

### Update via the API

`PUT /preview/v2/firewalls/{id}` replaces the full rule set.

```json theme={null}
{
  "rules": [
    { "direction": "ingress", "protocol": "tcp", "port": "22", "source": "0.0.0.0/0" }
  ]
}
```

## Deleting a firewall

Delete a firewall by name.

```bash theme={null}
sf firewalls delete web
```

Deleting a firewall fails if any instances still reference it.

## Limits

Firewalls enforce the following limits.

* 100 rules per firewall
* 100 firewalls per workspace, including the built-in `default`

## API reference

See the [Firewalls API](https://docs.sfcompute.com/api-reference/firewalls/list-firewalls.md) for programmatic access.
