Standalone Setup

This guide covers running Apoxy without a Kubernetes controller — either for local development or as a standalone edge node.

Two entrypoints

apoxy dev

apoxy dev [path/to/proxy.yaml] starts a complete local stack for development. It includes:

• A local Apoxy API server
• A backplane process
• A tunnelproxy process
• ClickHouse for logs (unless you provide an external address)
• Live reload when the config file or URL changes

This is the fastest way to iterate on a proxy configuration locally.

apoxy run

apoxy run starts specific runtime components defined in your config file's runtime.components section. The available component types are:

• kube-aggregation
• kube-mirror
• tunnel

Use apoxy run when you need explicit control over which components are running.

Choosing between them

• apoxy dev — Batteries-included local development loop around a proxy config file.
• apoxy run — Explicit control over individual runtime components for production or custom setups.
• apoxy tunnel run — Use this directly when you only need tunnel connectivity.

Runtime configuration

apoxy run reads the active config file and starts all components listed under runtime.components:

runtime:
  components:
    - type: kube-aggregation
      kubeAggregation:
        clusterName: "prod-us-east-1"
        namespace: "apoxy"
    - type: kube-mirror
      kubeMirror:
        mirror: "gateway"
    - type: tunnel
      tunnel:
        mode: "user"

Defaults

For kube-mirror:

• Namespace: apoxy
• Mirror modes: gateway, ingress, or all

For kube-aggregation:

• Namespace: apoxy

For tunnel:

• The active project must be set in your config for mirror and aggregation components to work.

Live reload with apoxy dev

apoxy dev watches the specified file or URL and re-applies configuration automatically when it changes. This makes it the faster entrypoint when you're iterating on a single proxy spec.