Quickstart

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.

Install the CLI

Install Apoxy locally:

brew install apoxy-dev/tap/apoxy

Or use go install:

go install github.com/apoxy-dev/apoxy/cmd/apoxy@latest

Upgrading

To upgrade to the latest version:

brew update && brew upgrade apoxy

The brew update step refreshes the Apoxy tap so that brew upgrade sees the latest release.

Log In

Authenticate to Apoxy Cloud:

apoxy auth login

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 HTTPRoute:

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

apoxy apply -f route.yaml

Apoxy routes traffic through the default Gateway to your backend.

Verify It Works

Check the status:

apoxy get gateway
apoxy get httproute

Send a test request to your gateway endpoint (Apoxy Cloud provides a public URL). If you're running self-hosted, port-forward to your Proxy and test locally.

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:

Routing: Advanced HTTPRoute rules, path prefixes, header matching.
Edge Functions: Deploy JS/WASM functions at the edge to transform requests or return responses.
Tunneling: Secure remote access to services behind NAT using QUIC tunnels.
TLS & DNS: Configure custom domains and certificates.

See Core Concepts to understand the architecture.