# Okapi install guide — Browser JavaScript

Okapi speaks the Sentry ingest wire format: this is the standard `@sentry/browser` SDK, pointed at your own Okapi instance instead of Sentry's.

The DSN in this generic guide is a placeholder. Get the real DSN from Project → Settings → DSN Keys. An agent with an admin Okapi MCP credential can also call `get_dsn`. Do not invent a DSN.

Do not run the Sentry wizard or any setup that signs in to Sentry's hosted service; nothing in this setup should contact it.

## 1. Install

```bash
npm install @sentry/browser
```

## 2. Initialize

### `src/main.js`

```javascript
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://YOUR_PUBLIC_KEY@YOUR_OKAPI_HOST/YOUR_PROJECT_ID",
  environment: "production",
});
```

Okapi authenticates ingest by the DSN's public key alone — there is no secret component, so the DSN is safe to ship in client-side bundles. Initialize as early as possible, before any other application code runs. Okapi's envelope endpoint has CORS enabled for cross-origin ingest from the browser — no extra configuration needed.

For React apps, use @sentry/react with the same init options. Initialize before other app code. Import sendOkapiTestEvent from src/okapi-test.js and call it from an app click handler after initialization; errors thrown in the devtools console are not captured.

### Optional Source maps (Vite)

Optional Source maps (Vite): install @sentry/vite-plugin and merge vite.config.js into your existing config. Change ./dist in filesToDeleteAfterUpload if build.outDir is customised.

```javascript
import { sentryVitePlugin } from "@sentry/vite-plugin";

process.env.SENTRY_CLI_NO_TELEMETRY ||= "1";

export default {
  build: { sourcemap: "hidden" },
  plugins: [sentryVitePlugin({
    sourcemaps: { filesToDeleteAfterUpload: ["./dist/**/*.map"] },
    url: "https://<your-okapi-host>",
    org: "<your-okapi-host>",
    project: "<project-slug>",
    authToken: process.env.SENTRY_AUTH_TOKEN,
    telemetry: false,
  })],
};
```

Create an upload token in Settings → Source maps and set SENTRY_AUTH_TOKEN in the build environment. When migrating from Sentry, replace Sentry's SENTRY_AUTH_TOKEN with an Okapi upload token and delete any leftover .env.sentry-build-plugin file (the plugin loads it into process.env). The config defaults SENTRY_CLI_NO_TELEMETRY to 1. Set SENTRY_CLI_NO_TELEMETRY=1 in the build environment too. The plugin's telemetry: false option does not disable CLI telemetry. Set url or sentryUrl to this instance's OKAPI_BASE_URL. A fresh CLI refuses uploads to a different host, but cached regions per org are honoured. Use this instance's host as org to isolate its CLI region cache; dotted hosts cannot collide with sentry.io slugs. Without a token, the build succeeds and skips uploads. See https://useokapi.app/docs/sdk-setup#source-map-uploads.

## 3. Send a test event

### `src/okapi-test.js`

```javascript
import * as Sentry from "@sentry/browser";

export function sendOkapiTestEvent() {
  Sentry.captureException(new Error("Okapi test event"));
}
```

## 4. Verify

Open the instance's dashboard → Issues. The test event should appear within a few seconds as a new issue. If the instance's MCP server exposes a `verify_installation` tool, call that instead of checking by hand — it reports the SDK name/version and whether only a synthetic test event has arrived yet.

## More

- Structured logs (same DSN, no separate shipper) and source map uploads: https://useokapi.app/docs/sdk-setup
- Connect over MCP once the SDK is wired up: https://useokapi.app/docs/mcp-agents