STEP 01Install the CLI STEP 02Log in STEP 03Route traffic STEP 04Apply config STEP 05Verify it works

This guide gets traffic routing through Apoxy in five minutes. Every project comes with a default Gateway and Proxy — you just need to create a Backend and an HTTPRoute.

Prereqs

A terminal with curl, an Apoxy Cloud account (free tier), and an upstream you can route to — anything with a public hostname works.

Install the CLI

Pick a platform. The CLI is a single static Go binary; no runtime, no daemon.

$terminalSH

# macOS and Linux — recommended for most workstations.
brew install apoxy-dev/tap/apoxy

$terminalSH

# If you already have a Go toolchain.
go install github.com/apoxy-dev/apoxy/cmd/apoxy@latest

Upgrading

To pick up the latest release:

$terminalSH

brew update && brew upgrade apoxy

The brew update step refreshes the Apoxy tap so that brew upgrade sees the latest release. If you installed via go install, re-run it with @latest.

Log in

Authenticate to Apoxy Cloud:

$terminalSH

apoxy auth

This opens your browser to create a session token. You'll be prompted to create or join an organization.

Route traffic to a backend

Every project starts with a default Gateway listening on ports 80 and 443. Create a file called route.yaml with a Backend and an HTTPRoute:

$route.yamlYAML

apiVersion: core.apoxy.dev/v1alpha2
kind: Backend
metadata:
  name: backend-service
spec:
  endpoints:
    - fqdn: api.internal.example.com

---
apiVersion: gateway.apoxy.dev/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
    - name: default
  hostnames:
    - api.example.com
  rules:
    - backendRefs:
        - kind: Backend
          name: backend-service
          port: 8080

Replace api.example.com with your domain and api.internal.example.com with the FQDN of your actual backend service.

Apply the configuration

$terminalSH

apoxy apply -f route.yaml

Apoxy routes traffic through the default Gateway to your backend.

Verify it works

Check the status of the objects you just created:

$terminalSH

apoxy gateway list
apoxy gateway routes list

Send a test request to your gateway endpoint. Apoxy Cloud provides a public URL — for self-hosted, port-forward to your Proxy and test locally.

$terminalSH

curl -H "Host: api.example.com" http://your-gateway-url/

You should see traffic flowing to your backend.

Next steps

Now that you have the basics working:

Advanced HTTPRoute rules — header matching, traffic splits, retries, and timeouts.
Tunnels & QUIC — access services behind NAT via connect-ip tunnels.
TLS & DNS — custom domains, BYO certs, managed Let's Encrypt issuance.

See Core concepts to understand the architecture, or dive into the CLI reference for every flag and command.