Basic tunnels

This guide starts a simple HTTP server on your machine and makes it reachable through your Apoxy domain. You'll have a public URL serving your local content in about two minutes.

Prerequisites

The Apoxy CLI installed and authenticated (apoxy auth login).
Python 3 available on your machine.

Start a local server

Start a basic HTTP server on port 8080:

python3 -m http.server 8080

Leave this running in its own terminal. It serves the current directory on http://localhost:8080.

Create the tunnel

In a second terminal, start a tunnel that connects your local machine to the Apoxy edge:

apoxy tunnel run my-tunnel --auto

The --auto flag creates the TunnelNode resource if it doesn't already exist. The tunnel establishes a QUIC connection to the nearest Apoxy edge and assigns your node an IPv6 address in your project's ULA prefix.

Create a Backend and route

When the tunnel connects, Apoxy's backplane makes it DNS-resolvable at my-tunnel.tun.apoxy.net. This FQDN is internal to Apoxy's routing layer — it isn't reachable from the public internet. Instead, you create a Backend that points to it, and a route that forwards public traffic through that Backend via the default Gateway.

Create a file called tunnel-route.yaml:

apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: my-tunnel-backend
spec:
  endpoints:
  - fqdn: my-tunnel.tun.apoxy.net

---
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: local-route
spec:
  parentRefs:
  - name: default
  hostnames:
  - demo.your-org.apoxy.app
  rules:
  - backendRefs:
    - kind: Backend
      name: my-tunnel-backend
      port: 8080

Replace demo.your-org.apoxy.app with a subdomain under your Apoxy organization.

Apply it:

apoxy apply -f tunnel-route.yaml

Verify

Check that the default Gateway accepted the route:

apoxy gateway get default

You should see local-route listed as an attached HTTPRoute.

Now hit your domain:

curl http://demo.your-org.apoxy.app/

You'll see the directory listing from your Python server. Traffic flows from the public domain through the Apoxy edge, into the Backend, down the QUIC tunnel, and into your local server on port 8080.

Clean up

Stop the tunnel and server with Ctrl-C, then remove the resources:

apoxy delete -f tunnel-route.yaml