Sandbox Networking

A sandbox contains multiple workloads connected by a private network, allowing them to communicate directly using hostnames or private IP addresses.

Within this private network, several special services operate:

DNS server: Resolves both internal and external DNS names.
NAT gateway: Provides access to external networks.
Service gateway: A transparent gateway that intercepts and proxies traffic to special DNS names.

DNS Server

The DNS server runs at a special private IP address and handles all DNS queries from sandbox workloads, including both internal and external names.

Internal DNS names include:

Hostnames of workloads (same as workload names).
Internal endpoint DNS names (.internal.sandbox suffix).
Special DNS names used by the Service Gateway (.g.sandbox base domain).

External DNS names (anything beyond internal names) are proxied by the DNS server. Queries are forwarded to upstream DNS servers rather than redirected or referred, because the upstream servers are part of the underlying infrastructure and should be isolated from sandbox workloads. This means the DNS resolution chain cannot be traced from inside a workload.

Hostname Aliases

The workload name is used as its primary hostname. Additional hostnames can be defined as aliases that resolve to the same workload IP address:

workspaces:
- name: example
  hostnames:
  - example1
  - example2

With this definition, example, example1, and example2 all resolve to the private IP of the example workspace. The hostnames field can be specified on any workload type.

DNS Extenders

Inside workspaces, custom DNS resolvers can be specified as DNS Extenders. These are consulted before upstream name servers when the query is not an internal DNS name.

There are two ways to configure DNS extenders:

1. Direct hostname mapping (similar to /etc/hosts):

Create a file like /etc/sandbox.d/dns/foo.hosts:

# IP  hostname1 hostname2 ...
192.168.1.100 internal-service service-alias

Unlike /etc/hosts, wildcards are supported:

*.foo matches one-level subdomains with .foo as the base domain.
**.foo matches any depth of subdomains with .foo as the base domain.

Multiple *.hosts files are supported and loaded in filename order.

2. Upstream DNS servers:

Create a file like /etc/sandbox.d/dns/foo.conf with JSON matching rules, one per line:

{"domains":[".foo", ".bar"],"types":["A"],"servers":["1.1.1.1"]}

Fields:

servers: used when a query matches the domains and query types.
servers values can be IP, IP:PORT, or UNIX-SOCKET-PATH.

Multiple *.conf files are loaded in filename order.

Warning: Upstream server configurations should only match specific domains and query types. Misconfigured upstream servers can cause workspace instability or high DNS latency.

NAT Gateway

The NAT gateway IP is configured as the default gateway inside workloads. All traffic to external networks is routed through it. By default, Crafting only allows Internet access and blocks all private subnets. For self-hosted deployments, the configuration can be customized to allow specific private subnets.

Service Gateway

The Service Gateway is a virtual gateway that intercepts traffic sent to special domain names. It handles:

.g.sandbox domains: Traffic is handled by specific modules based on the subdomain:
*.k8s.g.sandbox: Handled by the Kubernetes API server proxy module. See Kubernetes Development Experience.
*.llm.g.sandbox: Handled by LLM modules.
Internal endpoint DNS names (.internal.sandbox suffix): Traffic is routed by the Service Gateway to the correct destination sandbox workloads.

Network Isolation

By default, Crafting blocks all private subnets and allows only Internet access from inside sandbox workloads. For individual sandboxes or templates, Lockdown policies can be applied at a fine-grained level to block specific IP addresses and DNS names.

For self-hosted deployments, customization of accessible private subnets can be configured during deployment.