# Quickstart

> Get traffic flowing through Apoxy in under five minutes.

export const quickstartSteps = [
  { ix: "STEP 01", title: "Install the CLI", href: "#install-the-cli" },
  { ix: "STEP 02", title: "Log in", href: "#log-in" },
  { ix: "STEP 03", title: "Route traffic", href: "#route-traffic-to-a-backend" },
  { ix: "STEP 04", title: "Apply config", href: "#apply-the-configuration" },
  { ix: "STEP 05", title: "Verify it works", href: "#verify-it-works" },
];

<Steps steps={quickstartSteps} />

---

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**.

<Callout label="Prereqs">
A terminal with `curl`, an Apoxy Cloud account ([free tier](https://dashboard.apoxy.dev)), and
an upstream you can route to — anything with a public hostname works.
</Callout>

## Install the CLI

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

<CodeTabs>
  <CodeTab label="Homebrew">
    ```bash
    # macOS and Linux — recommended for most workstations.
    brew install apoxy-dev/tap/apoxy
    ```
  </CodeTab>
  <CodeTab label="go install">
    ```bash
    # If you already have a Go toolchain.
    go install github.com/apoxy-dev/apoxy/cmd/apoxy@latest
    ```
  </CodeTab>
</CodeTabs>

### Upgrading

To pick up the latest release:

```bash title="terminal"
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:

```bash title="terminal"
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:

```yaml title="route.yaml"
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

```bash title="terminal"
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:

```bash title="terminal"
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.

```bash title="terminal"
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](/docs/guides/routing-traffic.md) — header matching, traffic splits, retries, and timeouts.
- [Tunnels & QUIC](/docs/guides/basic-tunnels.md) — access services behind NAT via `connect-ip` tunnels.
- [TLS & DNS](/docs/guides/custom-domains.md) — custom domains, BYO certs, managed Let's Encrypt issuance.

See [Core concepts](/docs/getting-started/core-concepts.md) to understand the architecture, or dive into the
[CLI reference](/docs/reference/cli.md) for every flag and command.