---
title: http_proxy
description: Route local HTTP and WebSocket traffic between development servers.
---

# `http_proxy`

`http_proxy` starts a local reverse proxy for development servers. It forwards ordinary HTTP requests and WebSocket upgrades through one public origin, avoiding browser CORS configuration when the client and backend use separate servers.

```starlark
load("@http@1", "http_proxy")

http_proxy(
    "http://127.0.0.1:4321",
    [
        ("/greeter", "http://127.0.0.1:8001/greeter"),
        ("/", "http://127.0.0.1:8002"),
    ],
)
```

The proxy is a long-running root task. Declare the frontend and backend development servers as independent tasks in the same entrypoint; all three start concurrently.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `listen` | Yes | Absolute `http://` URL with an explicit nonzero port. |
| `routes` | Yes | Non-empty ordered list of `(path prefix, target URL)` string tuples. |
| `deps` | No | Dependencies that must complete before the proxy starts serving. Defaults to `[]`. |

Routes use declaration order. A prefix matches its exact path or a child path separated by `/`; `/greeter` does not match `/greeterish`. `/` is the catch-all route. Unmatched requests return HTTP 404.

The matched prefix is replaced by the target URL path. For example, `("/api", "http://127.0.0.1:8001/backend")` maps `/api/users?id=1` to `/backend/users?id=1`. Queries are preserved exactly. Route prefixes must be canonical, unescaped paths without a trailing slash. Requests containing encoded `/` or `\` path separators return HTTP 400.

Targets may use HTTP or HTTPS. The proxy connects directly rather than using process proxy environment variables, verifies normal HTTPS certificates, sets the upstream `Host`, and replaces client-supplied forwarding headers with trusted `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto` values. An unavailable target returns HTTP 502.

WebSocket handshakes and upgraded connections use the same routing and path replacement rules. Canceling the xx run closes the listener, ordinary requests, idle upstream connections, and active upgraded tunnels.

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/lsp.md
Title: Editor Support
Description: Configure an editor to use xx's built-in Starlark language server.

URL: https://withxx.dev/packages/cloudflare/cf_d1_create.md
Title: cf_d1_create
Description: Provision a Cloudflare D1 database with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_kv_create.md
Title: cf_kv_create
Description: Provision a Cloudflare Workers KV namespace with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_queue_create.md
Title: cf_queue_create
Description: Provision and configure a Cloudflare Queue with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_r2_create.md
Title: cf_r2_create
Description: Provision and configure a Cloudflare R2 bucket with Wrangler.

URL: https://withxx.dev/packages/cloudflare/cf_worker_config.md
Title: cf_worker_config
Description: Define an in-memory Cloudflare Worker configuration.

URL: https://withxx.dev/packages/cloudflare/cf_wrangler_deploy.md
Title: cf_wrangler_deploy
Description: Deploy a Cloudflare Worker with a temporary Wrangler configuration.

URL: https://withxx.dev/packages/cloudflare/cf_wrangler_dev.md
Title: cf_wrangler_dev
Description: Run one or more Cloudflare Workers with Wrangler dev.

URL: https://withxx.dev/packages/cmake/cmake.md
Title: cmake
Description: Activate managed CMake for dependent tasks.

URL: https://withxx.dev/packages/cmake/cmake_build.md
Title: cmake_build
Description: Build a generated project with managed CMake.

URL: https://withxx.dev/packages/cmake/cmake_generate.md
Title: cmake_generate
Description: Generate a project build system with managed CMake.

URL: https://withxx.dev/packages/doppler/doppler_secrets.md
Title: doppler_secrets
Description: Load Doppler secrets into dependent task environments.

URL: https://withxx.dev/packages/git/git_clone.md
Title: git_clone
Description: Materialize a pinned Git source tree with host Git configuration and access.

URL: https://withxx.dev/packages/git/git_commit.md
Title: git_commit
Description: Stage and commit changes in a Git repository.

URL: https://withxx.dev/packages/git/git_init_repository.md
Title: git_init_repository
Description: Ensure an empty SHA-1 or SHA-256 Git repository exists.

URL: https://withxx.dev/packages/git/git_push.md
Title: git_push
Description: Push commits from a Git repository.

URL: https://withxx.dev/packages/git/git_semver_latest.md
Title: git_semver_latest
Description: Read the latest semantic version from local Git tags.

URL: https://withxx.dev/packages/git/git_semver_next.md
Title: git_semver_next
Description: Calculate the next semantic version from local Conventional Commits.

URL: https://withxx.dev/packages/git/git_sha.md
Title: git_sha
Description: Resolve a local Git revision to its commit ID.

URL: https://withxx.dev/packages/git/git_tag.md
Title: git_tag
Description: Create a lightweight or annotated Git tag.

URL: https://withxx.dev/packages/go/go.md
Title: go
Description: Activate a managed Go SDK for dependent tasks.

URL: https://withxx.dev/packages/go/go_binary.md
Title: go_binary
Description: Build a Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_install.md
Title: go_install
Description: Install a versioned Go command for dependent tasks.

URL: https://withxx.dev/packages/go/go_protobuf.md
Title: go_protobuf
Description: Install protoc-gen-go and provide it as a Protobuf generator.

URL: https://withxx.dev/packages/go/go_run.md
Title: go_run
Description: Run a local program or versioned Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_test.md
Title: go_test
Description: Test Go packages with a managed SDK.

URL: https://withxx.dev/packages/http/http_proxy.md
Title: http_proxy
Description: Route local HTTP and WebSocket traffic between development servers.

URL: https://withxx.dev/packages/io/io_append_text.md
Title: io_append_text
Description: Append text to a file asynchronously.

URL: https://withxx.dev/packages/io/io_copy.md
Title: io_copy
Description: Copy a file or directory asynchronously.

URL: https://withxx.dev/packages/io/io_glob.md
Title: io_glob
Description: Find project files and directories with recursive glob patterns.

URL: https://withxx.dev/packages/io/io_read_text.md
Title: io_read_text
Description: Read a text file during build evaluation.

URL: https://withxx.dev/packages/io/io_rm.md
Title: io_rm
Description: Remove a file asynchronously.

URL: https://withxx.dev/packages/io/io_rmdir.md
Title: io_rmdir
Description: Remove a directory tree asynchronously.

URL: https://withxx.dev/packages/io/io_stat.md
Title: io_stat
Description: Read file information during build evaluation.

URL: https://withxx.dev/packages/io/io_write_text.md
Title: io_write_text
Description: Write text to a file asynchronously.

URL: https://withxx.dev/packages/ninja/ninja.md
Title: ninja
Description: Activate managed Ninja for dependent tasks.

URL: https://withxx.dev/packages/nodejs/nodejs.md
Title: nodejs
Description: Activate managed Node.js for dependent tasks.

URL: https://withxx.dev/packages/nodejs/npm_install.md
Title: npm_install
Description: Install dependencies with the package.json-selected manager.

URL: https://withxx.dev/packages/nodejs/npm_run.md
Title: npm_run
Description: Run a project package script with the package.json-selected manager.

URL: https://withxx.dev/packages/nodejs/npx_run.md
Title: npx_run
Description: Run a versioned npm package command with managed npx.

URL: https://withxx.dev/packages/os/env_append.md
Title: env_append
Description: Append an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_get.md
Title: env_get
Description: Read a value from a task environment while evaluating Starlark.

URL: https://withxx.dev/packages/os/env_prepend.md
Title: env_prepend
Description: Prepend an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_set.md
Title: env_set
Description: Set an environment variable for dependent tasks.

URL: https://withxx.dev/packages/os/env_unset.md
Title: env_unset
Description: Remove an environment variable from dependent tasks.

URL: https://withxx.dev/packages/os/os_arch.md
Title: os_arch
Description: Identify the host processor architecture.

URL: https://withxx.dev/packages/os/os_kernel.md
Title: os_kernel
Description: Identify the host operating system kernel.

URL: https://withxx.dev/packages/os/os_msvc.md
Title: os_msvc
Description: Activate the host Microsoft Visual C++ tools.

URL: https://withxx.dev/packages/os/os_run.md
Title: os_run
Description: Run a command from a project directory.

URL: https://withxx.dev/packages/os/os_system_tools.md
Title: os_system_tools
Description: Activate standard host operating-system utilities.

URL: https://withxx.dev/packages/os/os_xcode.md
Title: os_xcode
Description: Activate the host Xcode tools.

URL: https://withxx.dev/packages/os/path_make_absolute.md
Title: path_make_absolute
Description: Resolve a relative path from the project root.

URL: https://withxx.dev/packages/protobuf/protobuf_generate.md
Title: protobuf_generate
Description: Generate source code with a managed Protobuf compiler.

URL: https://withxx.dev/packages/protobuf/protobuf_generator.md
Title: protobuf_generator
Description: Adapt an installed protoc plugin dependency for code generation.

URL: https://withxx.dev/packages/protobuf/protoc.md
Title: protoc
Description: Activate a managed Protobuf compiler for dependent tasks.

URL: https://withxx.dev/packages/secrets/xx_secrets.md
Title: xx_secrets
Description: Load xx project secrets into dependent task environments.

URL: https://withxx.dev/packages/stripe/stripe.md
Title: stripe
Description: Activate a managed Stripe CLI for dependent tasks.

URL: https://withxx.dev/packages/stripe/stripe_listen.md
Title: stripe_listen
Description: Forward Stripe webhook events to a local endpoint.

URL: https://withxx.dev/packages/text/text_template.md
Title: text_template
Description: Render Go text templates from Starlark data and functions.

URL: https://withxx.dev/packages/xxrpc/xxrpc_client.md
Title: xxrpc_client
Description: Generate typed HTTP and WebSocket RPC clients for ECMAScript or Go.

URL: https://withxx.dev/packages/xxrpc/xxrpc_handler.md
Title: xxrpc_handler
Description: Generate typed framework-neutral ECMAScript RPC handler classes.

URL: https://withxx.dev/packages/zig/zig.md
Title: zig
Description: Activate managed Zig for dependent tasks.

URL: https://withxx.dev/packages/zig/zig_cc.md
Title: zig_cc
Description: Configure managed Zig as a C and C++ compiler.

URL: https://withxx.dev/packages.md
Title: Built-in Packages
Description: Versioned toolchains, commands, and task environment helpers provided by xx.

URL: https://withxx.dev/secrets.md
Title: Secret manager
Description: Store project secrets locally and provide them to xx tasks.

URL: https://withxx.dev/xxrpc.md
Title: xxRPC
Description: Design portable xxRPC contracts that keep application semantics in Protobuf.
-->