Skip to main content
When you build a custom app (a React/Vite bundle you ship with oxy publish), you usually want to run it locally with pnpm dev — but a local app has no Oxy identity, no auth, and no data. oxy proxy closes that gap: it lets your local app call a real cloud Oxy and return real data, so you can confirm your queries, charts, and functions work before you publish. It’s the same idea as vercel dev or Cloudflare’s remote bindings: your code runs locally, your data comes from the cloud.

​
How it works

oxy proxy starts a small local proxy on port 3000 — exactly where a local oxy serve would run. Your dev server keeps serving your app (with hot reload untouched) and forwards its Oxy calls to the proxy, which attaches your oxy login token and forwards them to the cloud environment you chose.
Because the proxy sits on port 3000, the @oxy-hq/vite-plugin — whose default Oxy target is already localhost:3000 — needs no configuration. Your app just starts hitting cloud data.
Your token stays inside the oxy proxy process. It is added to requests server-side and is never exposed to browser JavaScript or written to a .env.

​
Quick start

1

Log in to the environment you want data from

This caches a token per environment (dev, staging, production). Use the environment whose data you want to develop against.
2

Start the proxy

You’ll see a banner confirming the target and the active guardrails.
3

Start your app as usual

Open your dev server (e.g. http://localhost:5173). Your app now shows real data from the dev environment.

​
What you can access

oxy proxy forwards requests with your own oxy login token, so you can only reach data you’re already allowed to see. Access to an app’s data is granted if you are:
  • a member of the app’s organization, or
  • an Oxy app-admin, or
  • a partner admin with the manage apps capability over the org’s partner (so a partner’s developers can build against their managed orgs without being org members).
If you aren’t authorized for the app’s org, requests return 403 — the same rule the deployed app enforces.

​
Guardrails

Because you may be pointing at a real (possibly production) environment, side effects are off by default: Reads — query and semantic-query — are always forwarded; those are what you need to “validate the data.”
--allow-writes and --yes let your local app trigger real function/agent executions on the target environment. Use them deliberately, and prefer a dev or staging env over production.

​
Options

​
Troubleshooting

not authenticated for <target> — run oxy login --env <env> first (for the same environment you pass to oxy proxy). could not bind 127.0.0.1:3000 — something is already on port 3000 (often a local oxy serve). Stop it, or run oxy proxy --port <n> and point your dev server’s Oxy proxy at that port. side-effecting call held — your app called a function / agent / procedure. Re-run with --allow-writes if you intend those to execute against the target. Empty or 403 responses — you may not be authorized for the app’s organization. Confirm you’re a member, an app-admin, or a partner admin with manage apps over that org.