> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development with oxy proxy

> Run a custom app on your machine against a real cloud Oxy's data, so you can verify you're getting the right results before you publish.

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.

```text theme={null}
  browser ──▶ pnpm dev (:5173, serves your app + hot reload)
                  │  Oxy calls ↓
                  ▼
            oxy proxy (:3000)  ── adds your token ──▶  cloud (--env dev)
```

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.

<Note>
  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`.
</Note>

## Quick start

<Steps>
  <Step title="Log in to the environment you want data from">
    ```bash theme={null}
    oxy login --env dev
    ```

    This caches a token per environment (`dev`, `staging`, `production`). Use the
    environment whose data you want to develop against.
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    # run from your custom app's repo (it reads oxy-app.json for the target)
    oxy proxy --env dev
    ```

    You'll see a banner confirming the target and the active guardrails.
  </Step>

  <Step title="Start your app as usual">
    ```bash theme={null}
    pnpm dev
    ```

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

## 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:

| Behavior                                      | Default                                            | Opt in           |
| --------------------------------------------- | -------------------------------------------------- | ---------------- |
| Usage/tracking events                         | **dropped** (won't pollute the target's analytics) | `--allow-events` |
| Functions (`/fn`), agent runs, procedure runs | **held** — rejected with `409` until you opt in    | `--allow-writes` |
| Pointing at a production target               | **blocked**                                        | `--yes`          |

Reads — `query` and `semantic-query` — are always forwarded; those are what you
need to "validate the data."

<Warning>
  `--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`.
</Warning>

## Options

| Flag             | Description                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--env <name>`   | Environment to resolve the target + token from (same as `oxy login --env`). Defaults to `production`.               |
| `--target <url>` | Explicit Oxy base URL; overrides `--env`.                                                                           |
| `--port <n>`     | Local port (default **3000**). Change it if 3000 is taken — then point your dev server's Oxy proxy at the new port. |
| `--allow-events` | Forward tracking events instead of dropping them.                                                                   |
| `--allow-writes` | Forward `/fn`, agent, and procedure calls instead of holding them.                                                  |
| `--yes`          | Confirm proxying to a production target.                                                                            |

## 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.