Network Policies

Every Workspace can restrict the network destinations that its processes, including nested containers and AI agents, are allowed to reach via egress rules. The rules are enforced by the Workspace's supervisor outside of the sandbox using nftables, which means that nothing running inside the Workspace, even as root, can modify or bypass them.

Default Behavior

Without any configuration, a Workspace can reach the public internet, while all private networks are denied. More precisely:

Always denied, regardless of any configuration: the Workspace's supervisor and pod addresses, the pod's default gateway, loopback addresses outside of the sandbox, and link-local addresses such as the cloud metadata endpoint (i.e. 169.254.169.254).
Denied by default: the non-public networks, i.e. 10.0.0.0/8, 100.64.0.0/10, 172.16.0.0/12, 192.168.0.0/16, the other IPv4 special-purpose ranges, multicast, and the IPv6 unique local (fc00::/7) and special-purpose ranges. This typically includes the Kubernetes pod and service networks, the Kubernetes API and your private networks.
Allowed by default: every other (i.e. publicly routable) destination.

note

Workspaces do not need any network access to your private networks in order to access your private resources. Octelium Services remain reachable via secretless access through the Workspace's Octelium tunnel, which is authorized and audited on a per-request basis by Octelium Policies (read more here).

Egress Rules

The spec.runtime.network.egress field defines a defaultAction and a list of rules. Each rule matches a list of CIDRs (IPv4 or IPv6) and, optionally, a list of destination ports, which match both TCP and UDP. Here is an example that keeps the public internet reachable while blocking a few specific destinations:

spec:
  runtime:
    network:
      egress:
        defaultAction: ALLOW_PUBLIC
        rules:
          # Block a whole provider range
          - action: DENY
            cidrs:
              - 203.0.113.0/24
          # Block outgoing SMTP everywhere
          - action: DENY
            cidrs:
              - 0.0.0.0/0
              - ::/0
            ports:
              - 25
              - 465
              - 587
          # Allow one internal host on HTTPS only
          - action: ALLOW
            cidrs:
              - 10.20.30.40/32
            ports:
              - 443

The rules are evaluated as follows:

The rules are unordered. A destination matched by a DENY rule is denied even if it is also matched by an ALLOW rule.
A destination that is not matched by any rule falls back to the defaultAction:
- ALLOW_PUBLIC (the default) allows the publicly routable destinations and denies the non-public ones listed above.
- DENY denies everything that is not explicitly allowed.
The always-denied destinations listed above are denied even if they are matched by an ALLOW rule.

A Workspace can have up to 64 rules, each with up to 64 CIDRs and 64 ports. Invalid CIDRs, rules without CIDRs or without an action, and invalid ports are rejected when the Workspace or Template is created or updated.

Default-Deny Workspaces

For untrusted code and autonomous AI agents, you can deny everything by default and only allow the destinations that are actually needed (e.g. your package registries). Here is an example:

spec:
  runtime:
    network:
      egress:
        defaultAction: DENY
        rules:
          # The DNS resolver of the sandbox
          - action: ALLOW
            cidrs:
              - 8.8.8.8/32
            ports:
              - 53
          # Your package registry mirror
          - action: ALLOW
            cidrs:
              - 198.51.100.10/32
            ports:
              - 443

Keep the following in mind when using DENY as the default action:

DNS: the sandbox resolves names via 8.8.8.8, which therefore needs to be allowed on port 53, as shown above.
Image pulls and builds are not affected since they happen before the policy is applied. Repository clones, dotfiles and devcontainer feature downloads, however, happen inside the sandbox, which means that your git host and registries need to be allowed, or reached through an Octelium Service instead.
Octelium connectivity: the egress rules also apply to the tunnel of the Workspace's own octelium connect process. If the Workspace needs secretless access to Octelium Services, allow the public addresses of your Cluster's Gateways (you can list them via octeliumctl get gateway -o yaml). Everything that flows through the tunnel is then governed by Octelium Policies instead.

note

For AI agents, a default-deny network policy combined with secretless access to a small set of authorized Octelium Services (e.g. an LLM gateway, a read-only database and your git host) gives you a sandbox whose every external interaction is identity-based, authorized on a per-request basis and audited (read more here).

Templates and Updates

Egress rules can be defined in Templates as well as in Workspaces. The rules of both are combined, which means that a Template's DENY rules cannot be overridden by an ALLOW rule of a Workspace created from it. This lets Space admins define baseline restrictions for all the Workspaces of a Template while still letting individual Workspaces tighten them further.

The network policy is applied every time the Workspace starts. Changes to a Workspace's or Template's rules take effect on the next run. If the policy cannot be enforced, the Workspace is not started and its run fails with a NetworkPolicy failure.