Quickstart

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

This guide gets traffic routing through Apoxy in five minutes. Every project comes with a default Gateway and Proxy - you claim a hostname with a DomainRecord, then 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

# Any macOS or Linux machine. Requires curl and jq.
curl -fsSL https://raw.githubusercontent.com/apoxy-dev/apoxy/main/install.sh | bash

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 the shell script, re-run it to pick up the latest release.

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.

Claim a hostname

The shared default Gateway accepts routes only for hostnames that your project has claimed. Every Apoxy Cloud project gets its own zone under apoxy.app, so you can claim a hostname with no DNS setup. Find the name of your zone:

$terminalSH

apoxy domain zone list

Create a file called domain.yaml:

$domain.yamlYAML

apiVersion: core.apoxy.dev/v1alpha3
kind: DomainRecord
spec:
  zone: your-zone.apoxy.app
  name: api.your-zone.apoxy.app
  target:
    ref:
      group: gateway.apoxy.dev
      kind: Gateway
      name: default

Replace your-zone.apoxy.app with your zone in both fields. Apply the DomainRecord before the route:

$terminalSH

apoxy apply -f domain.yaml

To use a domain that you own, see Custom domains.

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.your-zone.apoxy.app
  rules:
    - backendRefs:
        - kind: Backend
          name: backend-service
          port: 8080

Replace api.your-zone.apoxy.app with the hostname you claimed 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 domain list
apoxy gateway routes list

Send a test request to the hostname you claimed. Apoxy runs DNS for your zone, so the name resolves to the gateway:

$terminalSH

curl http://api.your-zone.apoxy.app/

You should see the response from your backend. For self-hosted, port-forward to your Proxy and test locally.

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.