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

# Firewall

> Choose which ports your instances accept and from where.

Every environment has a firewall. Its rules decide which inbound ports the environment's instances accept, and from which addresses. Everything else is closed. The rules belong to the environment, so every instance in it follows the same rules, including ones you start later.

## The default

A new environment has one rule: **SSH (TCP port 22) from anywhere**. Nothing else is open until you add a rule.

Runcrate keeps the ports its own features use reachable from Runcrate only: the web terminal, the code editor, volume sync, and SSH for running commands from the dashboard. You do not need rules for them, and removing your SSH rule does not break them.

## A rule

| Field | What it means |
| - | - |
| Ports | One port, like `8080`, or a range, like `8000-8100` |
| Protocol | TCP or UDP |
| Sources | Who may connect: anywhere, or up to 20 IP addresses and CIDR ranges, IPv4 or IPv6. A single address, like `203.0.113.7`, means just that address |
| Description | Optional, up to 100 characters |

An environment holds up to 50 rules. Rules only open ports: anything no rule covers is closed. Ports published by programs in Docker containers follow the same rules.

> [!TIP]
>
> Prefer your own addresses over anywhere for anything that is not meant to be public. Find your address with `curl -s https://ifconfig.me`.

## How fast a change applies

A change reaches running instances within about a minute. Each instance checks for changes every 30 seconds. If an instance can't reach Runcrate for a while, it keeps the rules it last had: it never opens up on its own.

A change applies to new connections. Connections that are already open stay open until they end, the same as with cloud security groups. To cut one off, stop the program serving it or restart the instance.

Each instance shows whether its rules are in place: **enforced**, **pending** while a change is on its way, or **not enforced** if the instance could not apply them (the reason is shown with it).

## HTTPS links

To serve a web app or API on an instance at an HTTPS address, add an [HTTPS link](/docs/instances/https-links) on the instance. Links belong to each instance, not to the firewall: a link needs no rule, and its port stays closed to everyone but Runcrate's proxy unless a rule opens it.

## Older instances

Instances started before the firewall existed keep their ports exactly as they were, and show that the firewall does not manage them (`firewall.status` is `unmanaged` in the API). Start a new instance in the environment to bring it under the rules.

## Manage rules

**Ask your agent**

Connect the [Runcrate MCP server](/docs/mcp/setup), then ask in plain words:

```text theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
Open port 8080 to my IP 203.0.113.7.
```

The agent calls `add_firewall_rule` with `ports: "8080"` and `sources: ["203.0.113.7"]`. Agents can only change the rules of the environment they are connected to. See [MCP tools](/docs/mcp/tools#firewall).

**See the code**

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
# List the rules of the environment your key belongs to
curl https://www.runcrate.ai/api/v1/environments/current/firewall \
  -H "Authorization: Bearer $RUNCRATE_API_KEY"

# Open 8080 to one address
curl -X POST https://www.runcrate.ai/api/v1/environments/current/firewall \
  -H "Authorization: Bearer $RUNCRATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"protocol":"tcp","port_from":8080,"sources":["203.0.113.7"],"description":"demo app"}'

# Change a rule, or remove it
curl -X PATCH https://www.runcrate.ai/api/v1/environments/current/firewall/<rule-id> \
  -H "Authorization: Bearer $RUNCRATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sources":["anywhere"]}'
curl -X DELETE https://www.runcrate.ai/api/v1/environments/current/firewall/<rule-id> \
  -H "Authorization: Bearer $RUNCRATE_API_KEY"
```

`current` is the environment your API key belongs to; you can also pass an environment id. An API key only reaches its own environment, and only workspace owners and admins can change rules. `GET /api/v1/instances/{id}` shows each instance's `firewall`: its `status` (`enforced`, `pending`, `not_enforced` with an `error`, or `unmanaged` for an instance started before the firewall) and the `rules`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.