This guide covers three key aspects of networking on Instruqt:
  1. 1.
    Inbound traffic from learners and external systems to the sandbox hosts
  2. 2.
    Host to host communication between sandbox hosts
  3. 3.
    Outbound traffic from sandbox hosts to the public internet

Inbound traffic

There are two ways to send traffic to sandbox hosts on Instruqt:
  • Authenticated web traffic from learners through the Instruqt web proxy (
  • Unauthenticated TCP/UDP traffic to sandbox virtual machines, only if explicitly enabled (

Authenticated web traffic from learners

If you use a service tab in Instruqt, we forward requests from learners to the sandbox hosts through the Instruqt web proxy:
The features of the proxy include the following:
  • Allowing requests from logged-in learners only
  • Forwarding request to both containers and virtual machines
  • Terminating the HTTPS connection on the proxy and forwarding plain HTTP (or HTTPS if the port contains 443)
The proxy uses a formatted subdomain The web proxy uses a formatted subdomain to decide where to forward a request to:
There are three components in the subdomain:
  • Hostname: The name of the sandbox host in config.yml. (A sandbox host is a VM or a container.)
  • Port: The port to forward the traffic to. If you're forwarding traffic to a container, make sure to expose the port in config.yml.
  • Participant ID: An identifier that uniquely identifies a sandbox environment. You can access the participant ID on any sandbox host through the environment variable INSTRUQT_PARTICIPANT_ID
No header rewriting The web proxy does not support rewriting of Host and Location headers. If your service tab breaks because your service redirects to an internal hostname, make sure to configure the formatted subdomain as a virtual host.
Using an HTTPS endpoint on the sandbox host If the port contains 443 (examples include 443, 8443, and 4431), the proxy expects an HTTPS endpoint on the sandbox host. Our proxy accepts any (self-signed) non-expired TLS certificate
To embed a web service in a tab, use a service tab, not a website tab. Use a website tab to embed external websites.

Unauthenticated TCP/UDP traffic to sandbox virtual machines

By default, sandbox hosts are not exposed to the public internet. You can change that behavior.
  • Sandbox virtual machines have an external IP address. You can allow external ingress traffic to some ports or port ranges.
  • Sandbox containers can never receive direct traffic from external sources.
You can allow external ingress traffic to sandbox virtual machines using the attribute allow_external_ingress in config.yml (There is currently no way to set this property using the Web UI. Install the CLI first and pull your track to edit config.yml)
version: "2"
- name: host01
image: ubuntu-minimal-2004-lts
shell: /bin/bash
machine_type: n1-standard-1
- http
- https
- high-ports
You can specify one or more ports or port ranges. There are three valid values:
  • http: Port 80 (HTTP)
  • https: Port 443 (HTTPS)
  • high-ports: Port range 1024-65535, excluding 15770-15779 which are reserved for Instruqt use.

Resolving the external IP of a sandbox VM

To connect to a sandbox VM from an external system, you'll need to know its external IP address. Instruqt adds two temporary DNS records for every sandbox VM with allow_external_ingress enabled:
  • *.[HOSTNAME].[SANDBOX ID] (wildcard record)
Here are three examples of fully qualified host names that resolve to the same sandbox VM:
  • (due to the wildcard)
  • (due to the wildcard)
Run this snippet on the sandbox VM to print its fully qualified hostname:
# Prints the hostname of the sandbox host
echo $HOSTNAME.$
The environment variable INSTRUQT_PARTICIPANT_ID contains the sandbox identifier.). Sandboxes are created on-demand for every track play and every sandbox has a unique identifier.
If the attribute allow_external_ingress is empty, we do not add DNS records.

Host to host communication

All hosts (container and virtual machines) in a sandbox can communicate with one another. Instruqt provides internal DNS. If you add a host with the name host01 , and another host with the name host02, they can reach one another using their local name. Both container to container, container to VM (and vice versa) work:
[email protected]:~# ping host02 -c 1
PING host02.cn7p5alqphbi.svc.cluster.local ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=63 time=1.34 ms

Outbound traffic from sandbox hosts

Sandbox hosts can connect to the public internet without limitations

Last modified 7d ago