> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.islo.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server.

# Gateways

> Configure network policies and credential injection with Islo gateways.

Gateways control how your sandbox connects to external services. A gateway profile is a network policy plus an ordered set of rules — each rule matches outbound traffic by host (and optionally path/method) and decides whether to allow it, deny it, or inject credentials before forwarding.

## What Gateways Do

When a sandbox is attached to a gateway profile, Islo:

1. **Applies network policies** — controls which external endpoints the sandbox can reach.
2. **Injects credentials** — automatically attaches API keys, tokens, and secrets to outbound requests.
3. **Routes traffic** — proxies through Islo's gateway so requests can be audited and rate-limited.

Credentials never reach the sandbox process — authentication happens at the host/network layer.

## Using a Gateway Profile

### Via CLI flag

```bash
islo use my-sandbox --gateway-profile production-apis
```

### Via `islo.yaml`

```yaml
sandbox: my-project
gateway_profile: production-apis
```

Subsequent `islo use` calls without `--gateway-profile` pick up the default from `islo.yaml`. CLI flag wins when both are set.

### Precedence

1. `--gateway-profile` CLI flag — highest priority
2. `gateway_profile:` in `islo.yaml`
3. No gateway (default)

## Managing Gateway Profiles

### Create a profile

```bash
islo gateway create --name <name> [options]
```

| Option                      | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `--name <name>`             | Profile name (required)                                    |
| `--description <text>`      | Human-readable description                                 |
| `--default-action <action>` | `allow` or `deny` when no rule matches                     |
| `--internet-access <bool>`  | `true` / `false` — overall internet egress for the profile |
| `--is-default <bool>`       | Mark this profile as the team default                      |

```bash
islo gateway create \
  --name prod-api-gateway \
  --default-action deny \
  --internet-access true \
  --description "Production API access (deny by default)"
```

### List profiles

```bash
islo gateway ls
```

Add `--output json` for a structured array.

### Show a profile

```bash
islo gateway <name-or-id>
```

Prints profile settings and its current rules.

### Update a profile

```bash
islo gateway <name-or-id> update [options]
```

| Option                      | Description                      |
| --------------------------- | -------------------------------- |
| `--name <name>`             | Rename the profile               |
| `--description <text>`      | Set or replace the description   |
| `--clear-description`       | Remove the description           |
| `--default-action <action>` | `allow` or `deny`                |
| `--internet-access <bool>`  | Enable / disable internet egress |
| `--is-default <bool>`       | Mark or unmark as default        |

### Remove a profile

```bash
islo gateway <name-or-id> rm [-f]
```

`-f` / `--force` skips the confirmation prompt.

## Managing Rules

Rules are evaluated top-to-bottom by priority. The first match wins; if nothing matches, the profile's `--default-action` decides.

### List rules

```bash
islo gateway <name-or-id> rule ls
```

### Add a rule

```bash
islo gateway <name-or-id> add-rule --host <pattern> [options]
```

| Option                       | Description                                                         |
| ---------------------------- | ------------------------------------------------------------------- |
| `--host <pattern>`           | Host glob or exact host to match (required, e.g. `*.anthropic.com`) |
| `--path <pattern>`           | Optional path pattern to match                                      |
| `--method <method>`          | Restrict to one or more HTTP methods (`GET`, `POST`, …)             |
| `--action <action>`          | `allow` or `deny` when the rule matches                             |
| `--priority <n>`             | Insert the rule at this position (otherwise appended)               |
| `--rate-limit-rpm <n>`       | Rate limit in requests per minute                                   |
| `--provider-key <key>`       | Provider key used for credential injection                          |
| `--auth-mode <mode>`         | `bearer`, `basic`, or `header`                                      |
| `--auth-username <user>`     | Username for `basic` mode                                           |
| `--auth-name <name>`         | Header name for `header` mode                                       |
| `--auth-format <fmt>`        | Optional formatting hint for the injected credential                |
| `--filter-direction <dir>`   | `request`, `response`, or `both`                                    |
| `--filter-type <type>`       | `regex`, `content-type`, or `size-limit`                            |
| `--filter-pattern <pattern>` | Pattern for the content filter                                      |

Examples:

```bash
# Deny outbound calls to a specific host
islo gateway prod-api-gateway add-rule \
  --host "*.anthropic.com" \
  --action deny

# Allow OpenAI and inject a server-managed bearer token
islo gateway prod-api-gateway add-rule \
  --host "api.openai.com" \
  --action allow \
  --provider-key openai-prod \
  --auth-mode bearer \
  --rate-limit-rpm 60
```

### Update a rule

```bash
islo gateway <name-or-id> update-rule <rule-id> [options]
```

Most flags from `add-rule` are available again to change the value. Use the matching `--clear-*` flag to remove a field entirely.

| Option                                                                                            | Description                              |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `--priority <n>`                                                                                  | Move the rule to this position           |
| `--host <pattern>`                                                                                | Update the host pattern                  |
| `--path <pattern>` / `--clear-path`                                                               | Set or clear the path pattern            |
| `--method <method>` / `--clear-methods`                                                           | Replace or clear the HTTP methods filter |
| `--action <action>`                                                                               | `allow` or `deny`                        |
| `--rate-limit-rpm <n>` / `--clear-rate-limit`                                                     | Set or clear the rate limit              |
| `--provider-key <key>` / `--clear-provider-key`                                                   | Set or clear the provider key            |
| `--auth-mode <mode>`, `--auth-username`, `--auth-name`, `--auth-format` / `--clear-auth-strategy` | Update or clear the auth strategy        |
| `--filter-direction`, `--filter-type`, `--filter-pattern` / `--clear-content-filter`              | Update or clear the content filter       |

### Remove a rule

```bash
islo gateway <name-or-id> rm-rule <rule-id> [-f]
```

### Reorder rules

Assign explicit priorities in one call:

```bash
islo gateway prod-api-gateway reorder-rules \
  --rule rule_abc=10 \
  --rule rule_def=20 \
  --rule rule_ghi=30
```

`--rule` is repeatable; each value is `<rule-id>=<priority>`.

## Output

All `gateway` subcommands print human-readable tables by default. Add `--output json` to any of them for structured output suitable for scripts and AI agents.

## Common Workflows

### Build a deny-by-default profile

```bash
islo gateway create \
  --name strict-prod \
  --default-action deny \
  --internet-access true

islo gateway strict-prod add-rule --host "api.openai.com" --action allow --rate-limit-rpm 60
islo gateway strict-prod add-rule --host "*.anthropic.com" --action allow --rate-limit-rpm 60
islo gateway strict-prod add-rule --host "github.com"     --action allow
```

### Inject credentials so sandbox code doesn't see the key

```bash
islo gateway create --name prod-openai --default-action allow

islo gateway prod-openai add-rule \
  --host "api.openai.com" \
  --action allow \
  --provider-key openai-prod \
  --auth-mode bearer
```

Then run the sandbox with the profile:

```bash
islo use api-dev --gateway-profile prod-openai
```

Code inside the sandbox calls `https://api.openai.com/...` without any API key — the gateway adds the bearer token in flight.

## Troubleshooting

See [Troubleshooting → Gateways](/cli/troubleshooting/#gateways) for unknown profiles, blocked requests, and credential-injection problems.