# Okapi install guide — Nuxt

Okapi speaks the Sentry ingest wire format: this is the standard `@sentry/nuxt` 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/nuxt
```

## 2. Initialize

### `sentry.server.config.ts`

```typescript
import * as Sentry from "@sentry/nuxt";

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

### `sentry.client.config.ts`

```typescript
import * as Sentry from "@sentry/nuxt";

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

### `nuxt.config.ts`

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

export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],
  sourcemap: { client: "hidden", server: "hidden" },
  sentry: {
    sourcemaps: { filesToDeleteAfterUpload: [".output/public/**/*.map"] },
    sentryUrl: "https://<your-okapi-host>",
    org: "<your-okapi-host>",
    project: "<project-slug>",
    authToken: process.env.SENTRY_AUTH_TOKEN,
    telemetry: false,
  },
});
```

For Nuxt 3.7+ (3.14+ recommended), keep the config files at the project root; v11 bundles server init, so start with node .output/server/index.mjs without a preload. The deletion glob assumes the default Node server preset (`.output/public`). On other Nitro presets, point it at that preset's public directory, for example `.vercel/output/static/**/*.map` on Vercel or `dist/**/*.map` on Netlify. Request GET /api/okapi-test after starting the app, then remove the test route. 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

### `server/api/okapi-test.get.ts`

```typescript
import * as Sentry from "@sentry/nuxt";

export default defineEventHandler(() => {
  Sentry.captureException(new Error("Okapi test event"));
  return "Okapi test event sent";
});
```

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