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

# Egress policies

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

Egress policies control outbound connections from your workloads. Use them to filter traffic,
inject Vault secrets into requests, or route traffic through another domain.

<CardGroup cols={3}>
  <Card title="Filter" icon="shield-check" href="#filter-traffic">
    Control egress traffic
  </Card>

  <Card title="Inject secrets" icon="key-round" href="#inject-secrets">
    Protect credentials
  </Card>

  <Card title="Proxy" icon="route" href="#proxy-traffic">
    Route through another domain
  </Card>
</CardGroup>

## Create an egress policy

Define the policy's tag, mode, rules, managed rulesets, and deep packet inspection setting in a
JSON configuration file. For example, the following policy allows the traffic required by GitHub
Actions, plus requests to `example.com`. It also injects a Vault secret into the
`Authorization` header for requests to `example.com`:

```json theme={null}
{
  "tag": "your-network-policy",
  "description": "CI with access to example.com",
  "mode": "BLOCK",
  "deep_packet_inspection": true,
  "additional_rulesets": ["github-actions"],
  "rules": [
    {
      "op": "ALLOW",
      "matcher": {
        "match_domains": ["example.com"]
      }
    },
    {
      "op": "INJECT",
      "matcher": {
        "match_domains": ["example.com"]
      },
      "inject": {
        "header_name": "Authorization",
        "from_secret_id": "sec_example"
      }
    }
  ]
}
```

Save the configuration as `egress-policy.json`, then create the policy:

```bash theme={null}
nsc egress policy create --spec_file egress-policy.json
```

<Info>
  The `nsc egress policy` commands require **nsc v0.0.554** or later.
</Info>

See [`nsc egress policy create`](/docs/reference/cli/egress-policy-create#policy-configuration)
for configuration field descriptions.

### Rules

Rules are evaluated in order and apply to matching domains.

#### Filter traffic

`ALLOW` rules permit requests to matching domains. In `BLOCK` mode, the policy denies all requests
that are not allowed.

```json theme={null}
{
  "op": "ALLOW",
  "matcher": {
    "match_domains": ["example.com"]
  }
}
```

Policies can additionally include managed rulesets for GitHub Actions runners, Devboxes, and macOS workloads.
Namespace keeps these rulesets current as workload requirements change. Use the
`github-actions` ruleset for GitHub Actions runners and the
`devbox` ruleset for Devboxes so the policy allows the traffic required for their functionality.

The optional `macos` ruleset permits routine connections from macOS to Apple services. macOS workloads
can operate without it, but recurring denied requests to these services can add noise to the egress logs and make other relevant entries more difficult to identify.

#### Inject secrets

`INJECT` rules set an HTTP header to a value from [Namespace Vault](/docs/architecture/storage/secrets).
The secret is resolved outside the workload and its value is never exposed to it. `INJECT` requires deep
packet inspection.

```json theme={null}
{
  "op": "INJECT",
  "matcher": {
    "match_domains": ["example.com"]
  },
  "inject": {
    "header_name": "Authorization",
    "from_secret_id": "sec_example"
  }
}
```

#### Proxy traffic

`PROXY` rules route matching outbound HTTP traffic through another domain instead of connecting to the
destination directly. Set `proxy.via_domain` to the domain that should proxy those connections. `PROXY`
requires deep packet inspection.

```json theme={null}
{
  "op": "PROXY",
  "matcher": {
    "match_domains": ["example.com"]
  },
  "proxy": {
    "via_domain": "proxy.example.com"
  }
}
```

### Start in advisory mode

```json theme={null}
{
  "tag": "your-network-policy",
  "description": "CI with access to example.com",
  "mode": "ADVISORY",
```

Use `ADVISORY` mode to evaluate and record the same policy decisions as `BLOCK` mode without denying
requests. Review the [per-instance egress traffic](#per-instance-egress-traffic), add any required
domains, and then update `mode` to `BLOCK`. This avoids unexpectedly breaking a workload while
building its allow-list from real traffic.

```bash theme={null}
nsc egress policy update your-network-policy --spec_file egress-policy.json
```

## Use an egress policy

Workspace policies can be reused across GitHub Actions runner profiles, Devboxes, and instances
created through the Compute API.

### GitHub Actions runner profiles

Apply an egress policy to GitHub Actions runners through a runner profile. Open the profile in the
[web UI](https://cloud.namespace.so/workspace/actions/profiles) and select a workspace policy in its **network policy** settings.
The selected policy applies to every runner created from that profile.

<Info>
  Include the `github-actions` additional ruleset in policies used with GitHub Actions runners. It allows the traffic required for runner functionality.
</Info>

<CenteredImage width={700} alt="Network Policy settings with an egress policy selected" src="/docs/images/workspaces/egress-policy-ui.png" />

You can also configure it from the CLI:

```bash theme={null}
nsc github profile create \
  --tag "runner-with-policy" \
  --egress_policy_tag "your-network-policy"
```

### Devboxes

Apply an egress policy to Devboxes through a blueprint. Open the blueprint in the
[web UI](https://cloud.namespace.so/workspace/devboxes/blueprints) and select a workspace policy in its **network policy**
settings. The selected policy applies to every Devbox created from that blueprint.

<Info>
  Include the `devbox` additional ruleset in policies used with Devboxes. It allows the traffic required for Devbox functionality.
</Info>

### Compute API

To apply a policy per instance, set `network_policy.egress_policy_tag` on the `CreateInstance`
request. The tag must identify a policy in the instance's workspace and is mutually exclusive with
an inline `network_policy.egress` configuration. See the
[`CreateInstanceRequest.NetworkPolicy`](https://buf.build/namespace/cloud/docs/main%3Anamespace.cloud.compute.v1beta#namespace.cloud.compute.v1beta.CreateInstanceRequest.NetworkPolicy) API reference
for the complete schema.

## Observe egress traffic

### Workspace traffic

Namespace records outbound policy decisions and shows them in the
[Egress Filtering dashboard](https://cloud.namespace.so/workspace/egress). Requests are grouped by base domain and split
into **Allowed** and **Denied**, so you can confirm that required destinations are reachable and
spot unexpected traffic. You can also inspect decisions with
[`nsc egress logs`](/docs/reference/cli/egress-logs).

<CenteredImage width={700} alt="Egress Filtering dashboard grouping allowed and denied domains" src="/docs/images/workspaces/egress-traffic-ui.png" />

### Per-instance egress traffic

The workspace dashboard aggregates traffic across all workloads. To inspect a single workload,
open the instance and select its **Egress** tab. The per-instance view lists allowed and denied
requests.

<CenteredImage width={700} alt="Instance Egress tab showing allowed and denied outbound requests" src="/docs/images/workspaces/egress-instance-ui.png" />