oxyc publish),
you usually want to run it locally with pnpm dev — but a local app has no Oxy
identity, no auth, and no data. oxyc 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.
oxyc is Oxy’s command-line client. Install it once:
How it works
oxyc 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
oxyc login token and forwards them to the cloud environment you chose.
@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
oxyc 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
dev, staging, production, or a
deployment URL). Use the environment whose data you want to develop against.2
Start the proxy
3
Start your app as usual
http://localhost:5173). Your app now shows real
data from the dev environment.What you can access
oxyc proxy forwards requests with your own oxyc 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).
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.”
Debugging a function call
Every Oxy Function call through the proxy carries a trace — the one the SDK started, or one the proxy starts for it — and prints a line with the ids to look up when it fails:trace_id when you ask for help. When the call came from
@oxy-hq/sdk, it is also the traceId on the error your app received.
Options
Troubleshooting
no cached token for <target> — the proxy found no token. It still starts, but
only requests that carry their own sign-in will work. Run oxyc login --env <env>
for the same environment you pass to oxyc proxy. If you passed --token-env <var>,
set that variable instead: the cached login is never read when the flag names one.
port 3000 is already in use — something is already on port 3000 (often a
local oxy serve). Stop it, or run oxyc proxy --port <n> and point your dev
server’s Oxy proxy at that port.
refusing to proxy to a production target — the target is a production host.
Pass --yes if that is really what you want, or use --env dev.
409 with held_by_oxyc_proxy — your app called a function / agent /
automation. 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.