# Apoxy Documentation

> Documentation for the Apoxy platform. Each entry below links to the raw markdown of a single page.

## changelog

- [Changelog.](/docs/changelog.md): What changed and when. New features, breaking changes, security fixes.

## guides

- [Guides](/docs/guides.md): Task-focused walkthroughs for common Apoxy workflows.
- [CLRK guides](/docs/clrk/guides.md): Task-focused walkthroughs for CLRK workflows.
- [Basic tunnels](/docs/guides/basic-tunnels.md): Expose a local HTTP server on your Apoxy domain using a tunnel.
- [Run your first agent](/docs/clrk/guides/run-your-first-agent.md): Apply a minimal example under `clrk dev`, watch a sandbox spawn, and confirm the Anthropic API key never reaches the agent.
- [Tunnels with Docker](/docs/guides/tunnels-with-docker.md): Connect a running Docker container to the Apoxy edge using a tunnel.
- [Private services with VPC tunnels](/docs/guides/private-services-with-vpc-tunnels.md): Publish a private service through the default Gateway, or call it from an Apoxy compute Service.
- [GCE userspace VPC tunnels](/docs/guides/gce-vpc-tunnels.md): Run an alpha VPC tunnel agent on a Google Compute Engine VM and publish a private service through the default Gateway.
- [EC2 kernel-mode VPC tunnels](/docs/guides/ec2-vpc-tunnels.md): Run a VPC tunnel agent with a kernel TUN device on EC2 and publish a private service through the default Gateway.
- [Claude Code over HTTP](/docs/clrk/guides/claude-code-over-http.md): Stand up Claude Code as an internal HTTP service so callers can prompt it without holding the Anthropic API key.
- [Tuning tunnels](/docs/guides/tuning-tunnels.md): Adjust endpoint selection, connection pooling, and DNS behavior for tunnel clients.
- [Backend keep-alive](/docs/guides/backend-keep-alive.md): Tune your upstream server's HTTP keep-alive idle so Apoxy doesn't see intermittent 503s on traffic that races a backend-initiated close.
- [Package a custom agent](/docs/clrk/guides/package-a-custom-agent.md): Turn a Python, Node, or shell script into a CLRK agent: choose the right kind, honor the I/O contract, build an image, write the manifest, invoke.
- [Routing traffic](/docs/guides/routing-traffic.md): Attach routes to the default Gateway and verify traffic flow using the Gateway API.
- [Deploying compute Services](/docs/guides/deploying-compute-services.md): Build a JS/TS worker into a bundle, push it to an OCI registry, and serve it from the Apoxy edge with `apoxy deploy`.
- [Schedule recurring agents](/docs/clrk/guides/schedule-recurring-agents.md): Run a TaskAgent on a cron schedule with a fixed payload. Same agent, same image, same observability - different trigger.
- [Custom domains](/docs/guides/custom-domains.md): Attach a customer-owned domain to Apoxy's default Gateway with zero-downtime TLS provisioning.
- [Hide credentials from agents](/docs/clrk/guides/hide-credentials-from-agents.md): Keep API keys out of the agent process entirely. The proxy injects them after the request leaves the sandbox.
- [HTTP to HTTPS redirect](/docs/guides/http-to-https-redirect.md): Redirect HTTP traffic to HTTPS using the default Gateway's listeners.
- [Cap LLM spend per agent](/docs/clrk/guides/cap-llm-spend-per-agent.md): Set token budgets that the egress proxy enforces. The agent sees a 429 when over budget; the denial lands in OTLP for alerting.
- [Response compression](/docs/guides/response-compression.md): Compress HTTP responses with gzip, brotli, or zstd - enabled by default, customizable via HTTPRouteFilter.
- [Lock down agent egress](/docs/clrk/guides/lock-down-agent-egress.md): Default-deny outbound traffic. Allowlist the upstreams your agents actually need by hostname, CIDR, and port.
- [Routing to Kubernetes services](/docs/guides/routing-to-kubernetes-services.md): Address cluster services through a tunnel and the Apoxy edge.
- [Send telemetry to OTLP endpoints](/docs/clrk/guides/send-telemetry-to-otlp.md): Wire CLRK's request logs and traces to your observability backend. Per-EgressGateway configuration, OTLP/HTTP, no extra collector required.
- [Rotating the kube-controller certificate](/docs/guides/rotating-kube-controller-cert.md): Roll the per-cluster client certificate the Apoxy controller uses, without dropping the aggregated API.
- [Query fleet metrics](/docs/clrk/guides/query-fleet-metrics.md): Read fleet stats and chart data from CLRK's metrics API: a typed catalog plus a time-series query over the spans and logs your agents already emit.
- [Query gateway metrics](/docs/guides/query-gateway-metrics.md): Read current totals for a Gateway, chart requests over time broken down by route, and save your own metric recipe.
- [Trace requests through agents](/docs/clrk/guides/trace-requests-through-agents.md): Follow a single inbound request from ingress through sandbox through every LLM call it produced. Worked debugging session.
- [Query logs with Claude Code](/docs/guides/mcp-claude-code.md): Connect Claude Code to Apoxy's MCP server to query your proxy logs with natural language.
- [Authenticate users before agents](/docs/clrk/guides/authenticate-users-before-agents.md): Pattern: front the CLRK ingress with your own auth layer. CLRK does not authenticate inbound traffic itself.
- [Troubleshooting](/docs/guides/troubleshooting.md): Debug route attachments, tunnel connectivity, and common failure modes.
- [Persist state across runs](/docs/clrk/guides/persist-state-across-runs.md): Pattern: keep agent state in external storage so a multi-turn conversation can resume on the next invocation.

## getting-started

- [Overview](/docs/clrk/getting-started.md): What CLRK is and how the major pieces fit together.
- [Overview](/docs/getting-started.md): What Apoxy is and how the major pieces fit together.
- [Quickstart](/docs/clrk/getting-started/quickstart.md): Run your first sandboxed agent end-to-end in about a minute.
- [Quickstart](/docs/getting-started/quickstart.md): Get traffic flowing through Apoxy in under five minutes.
- [Core Concepts](/docs/getting-started/core-concepts.md): The building blocks of the Apoxy platform - projects, gateways, routing, backends, compute services, and more.
- [Local development](/docs/clrk/getting-started/local.md): How `clrk dev` brings up a complete CLRK stack on your laptop, and the flags you'll reach for as you iterate.
- [Kubernetes Install](/docs/getting-started/kubernetes.md): Install the Apoxy controller into a cluster, verify the install, and debug common failure modes.
- [Core concepts](/docs/clrk/getting-started/core-concepts.md): The CRDs CLRK installs and how they compose - agents, pools, egress, policies, and observability.
- [Standalone Setup](/docs/getting-started/direct.md): Start Apoxy locally or directly on a machine using the current CLI runtime commands.
- [Self-hosted gateway maintenance](/docs/guides/self-hosted-maintenance.md): Keep gateway replicas available during node maintenance and set connection drain times.

## reference

- [CLRK reference](/docs/clrk/reference.md): Reference documentation for CLRK.
- [Reference](/docs/reference.md): Apoxy reference documentation
- [CLI](/docs/clrk/reference/cli.md): Autogenerated command reference for the clrk CLI.
- [CLI](/docs/reference/cli.md): Autogenerated command reference for the apoxy CLI.
- [Local Secret CLI](/docs/reference/sealed-secrets.md): Seal Secrets, unseal manifests with cluster keys, and read values for local commands.
- [MCP server](/docs/reference/mcp.md): Model Context Protocol server reference for querying proxy logs with AI assistants.
- [Metrics API](/docs/reference/metrics.md): Read request rates, error counts, latency percentiles, and byte volumes for your project through typed time-series and snapshot endpoints, or scrape a self-hosted gateway pod with Prometheus.
- [HTTP APIs](/docs/clrk/reference/http-apis.md): REST API reference for the clrk.apoxy.dev Kubernetes-style resources served by the clrk apiserver.
- [HTTP APIs](/docs/reference/http-apis.md): REST API reference for all Kubernetes-style resources served by the per-project apiserver.
- [Controller metrics](/docs/reference/kube-controller-metrics.md): Prometheus metrics exposed by the in-cluster Apoxy controller, the stable subset customers can scrape and alert on, and how to wire them into Prometheus.
- [Infra Projects](/docs/reference/infra-projects.md): Internal desired-state records that assign projects to shards and report project API server health.
- [DaemonAgentMetrics](/docs/clrk/reference/clrk-metrics/daemonagentmetrics.md): API reference for Daemon Agent Metrics (metrics.clrk.apoxy.dev/v1alpha1)
- [AgentSandboxRevision](/docs/clrk/reference/clrk/agentsandboxrevisions.md): API reference for Agent Sandbox Revisions (clrk.apoxy.dev/v1alpha1)
- [Backend](/docs/reference/core/backends.md): API reference for Backends (core.apoxy.dev/v1alpha2)
- [Metric](/docs/clrk/reference/clrk-metrics/metrics.md): API reference for Metrics (metrics.clrk.apoxy.dev/v1alpha1)
- [AIProviderRoute](/docs/clrk/reference/clrk/aiproviderroutes.md): API reference for AI Provider Routes (clrk.apoxy.dev/v1alpha1)
- [CloudMonitoringIntegration](/docs/reference/core/cloudmonitoringintegrations.md): API reference for Cloud Monitoring Integrations (core.apoxy.dev/v1alpha2)
- [TaskAgentMetrics](/docs/clrk/reference/clrk-metrics/taskagentmetrics.md): API reference for Task Agent Metrics (metrics.clrk.apoxy.dev/v1alpha1)
- [Backend](/docs/clrk/reference/clrk/backends.md): API reference for backends (clrk.apoxy.dev/v1alpha1)
- [DomainRecord](/docs/reference/core/domainrecords.md): API reference for Domain Records (core.apoxy.dev/v1alpha3)
- [CredentialInjectionPolicy](/docs/clrk/reference/clrk/credentialinjectionpolicies.md): API reference for Credential Injection Policies (clrk.apoxy.dev/v1alpha1)
- [Domain](/docs/reference/core/domains.md): API reference for Domains (core.apoxy.dev/v1alpha3)
- [DaemonAgent](/docs/clrk/reference/clrk/daemonagents.md): API reference for Daemon Agents (clrk.apoxy.dev/v1alpha1)
- [DomainZone](/docs/reference/core/domainzones.md): API reference for Domain Zones (core.apoxy.dev/v1alpha3)
- [EgressDenyPolicy](/docs/clrk/reference/clrk/egressdenypolicies.md): API reference for Egress Deny Policies (clrk.apoxy.dev/v1alpha1)
- [Proxy](/docs/reference/core/proxies.md): API reference for Proxies (core.apoxy.dev/v1alpha2)
- [EgressGateway](/docs/clrk/reference/clrk/egressgateways.md): API reference for Egress Gateways (clrk.apoxy.dev/v1alpha1)
- [TunnelNode](/docs/reference/core/tunnelnodes.md): API reference for Tunnel Nodes (core.apoxy.dev/v1alpha)
- [EgressL4Route](/docs/clrk/reference/clrk/egressl4routes.md): API reference for Egress L4 Routes (clrk.apoxy.dev/v1alpha1)
- [FallbackRoutingPolicy](/docs/clrk/reference/clrk/fallbackroutingpolicies.md): API reference for fallbackroutingpolicies (clrk.apoxy.dev/v1alpha1)
- [Invocation](/docs/clrk/reference/clrk/invocations.md): API reference for invocations (clrk.apoxy.dev/v1alpha1)
- [LoggingPolicy](/docs/clrk/reference/clrk/loggingpolicies.md): API reference for Logging Policies (clrk.apoxy.dev/v1alpha1)
- [GatewayClass](/docs/reference/gateway/gatewayclasses.md): API reference for Gateway Classes (gateway.apoxy.dev/v1)
- [MCPRoute](/docs/clrk/reference/clrk/mcproutes.md): API reference for MCP Routes (clrk.apoxy.dev/v1alpha1)
- [Gateway](/docs/reference/gateway/gateways.md): API reference for Gateways (gateway.apoxy.dev/v1)
- [RateLimitPolicy](/docs/clrk/reference/clrk/ratelimitpolicies.md): API reference for Rate Limit Policies (clrk.apoxy.dev/v1alpha1)
- [GRPCRoute](/docs/reference/gateway/grpcroutes.md): API reference for gRPC Routes (gateway.apoxy.dev/v1)
- [TaskAgent](/docs/clrk/reference/clrk/taskagents.md): API reference for Task Agents (clrk.apoxy.dev/v1alpha1)
- [HTTPRoute](/docs/reference/gateway/httproutes.md): API reference for HTTP Routes (gateway.apoxy.dev/v1)
- [WorkerPool](/docs/clrk/reference/clrk/workerpools.md): API reference for Worker Pools (clrk.apoxy.dev/v1alpha1)
- [TCPRoute](/docs/reference/gateway/tcproutes.md): API reference for TCP Routes (gateway.apoxy.dev/v1alpha2)
- [TLSRoute](/docs/reference/gateway/tlsroutes.md): API reference for TLS Routes (gateway.apoxy.dev/v1alpha2)
- [UDPRoute](/docs/reference/gateway/udproutes.md): API reference for UDP Routes (gateway.apoxy.dev/v1alpha2)
- [DirectResponse](/docs/reference/extensions/directresponses.md): API reference for Direct Responses (extensions.apoxy.dev/v1alpha2)
- [EdgeFunctionRevision](/docs/reference/extensions/edgefunctionrevisions.md): API reference for Edge Function Revisions (extensions.apoxy.dev/v1alpha2)
- [EdgeFunction](/docs/reference/extensions/edgefunctions.md): API reference for Edge Functions (extensions.apoxy.dev/v1alpha2)
- [Build](/docs/reference/compute/builds.md): API reference for Builds (compute.apoxy.dev/v1alpha1)
- [EgressGateway](/docs/reference/compute/egressgateways.md): API reference for Egress Gateways (compute.apoxy.dev/v1alpha1)
- [EgressRoute](/docs/reference/compute/egressroutes.md): API reference for Egress Routes (compute.apoxy.dev/v1alpha1)
- [ServiceRevision](/docs/reference/compute/servicerevisions.md): API reference for Service Revisions (compute.apoxy.dev/v1alpha1)
- [Service](/docs/reference/compute/services.md): API reference for Services (compute.apoxy.dev/v1alpha1)