# Getting started

Connect one model to Omnious with `@omnious/provider`. This guide uses llama.cpp and a policy that accepts one new request at a time, without offering a cache commitment.

## Before you begin

Install Bun 1.3.14 or later and run a [supported model server](/providers/engines) with metrics enabled. The SDK ships ESM JavaScript and TypeScript declarations. Its CLI loads TypeScript configuration directly; Node.js is not a tested runtime.

Your agent must reach the engine's health, model discovery, and metrics endpoints. Omnious must separately reach its inference endpoint.

## Register your model

1. Request provider access in the Omnious web app and wait for approval.
2. In Provider config, enter your engine's API base URL and its credentials if needed.
3. Discover models or add one manually. Map its upstream model name to the canonical Omnious model, select its native protocol, and set its context window and capabilities.
4. Activate the model and save the configuration.
5. Generate a provider token. Copy it now; it is shown only once.

You can also import model capabilities and limits from an OpenRouter Provider Monitor 2.4 document, using a URL or JSON file. Imports do not set your pricing or capacity.

The model names have different jobs:

| Name               | Where you use it                                 | Example              |
| ------------------ | ------------------------------------------------ | -------------------- |
| Canonical model ID | Provider config and SDK `canonicalModelId`       | `openai/gpt-oss-20b` |
| Upstream model ID  | Engine adapter `model` and your inference server | `gpt-oss:20b`        |
| Preset model ID    | An inference user's request to Omnious           | `preset/coding`      |

Use the actual model name returned by your engine's `/v1/models` endpoint. The SDK currently connects one canonical model to one engine. Keep the account's active model mapping consistent with this configuration.

## Install the SDK

In a new directory:

```sh
bun init -y
bun add @omnious/provider
```

## Configure your provider

Create `provider.ts`. Replace the WebSocket host, engine URL, and model names with your own values.

```ts
import { defineProvider, llamaCpp } from "@omnious/provider";

const terms = {
  inputPerMTok: "0.35",
  outputPerMTok: "0.61",
};

export default defineProvider({
  url: "wss://your-omnious-host/providers/ws",
  canonicalModelId: "openai/gpt-oss-20b",
  engine: llamaCpp({
    baseUrl: "http://127.0.0.1:11434",
    model: "gpt-oss:20b",
  }),
  standingPrice: () => terms,
  quote: ({ metrics, activeRequests, pendingQuotes }) => {
    if (!metrics || metrics.waitingRequests > 0) return { accept: false };
    if (Math.max(activeRequests, metrics.runningRequests) + pendingQuotes >= 1)
      return { accept: false };
    return { accept: true, terms };
  },
});
```

Prices are USD strings per million tokens, with up to six decimal places. These example rates are not a pricing recommendation.

`standingPrice` publishes your input and output rates. `quote` decides whether to offer terms for each request. The policy above declines when metrics are unavailable, work is queued, or a request or binding quote already occupies its chosen budget. The SDK does not impose this limit for you.

The engine URL above is local to the agent. The endpoint saved in Provider config must be reachable by Omnious; an outbound WebSocket does not make a local model server reachable.

## Check the engine

```sh
bunx omnious-provider check ./provider.ts
```

This checks `/health`, `/v1/models`, and `/metrics` without connecting to Omnious. It validates that the selected model exists and the metrics match the adapter's contract. You do not need a provider token for this check.

If it fails, check the model name, metrics flag, engine version, and any engine credentials. See [Engines and metrics](/providers/engines).

## Connect to Omnious

Add your provider token to `.env` and make sure `.env` is in `.gitignore`:

```dotenv
OMNIOUS_PROVIDER_TOKEN=omv_live_replace_with_your_token
```

Then start the agent:

```sh
bunx omnious-provider start ./provider.ts
```

Startup checks the engine, restores connection state, and waits for Omnious to acknowledge the first standing-price update. Keep the process running to receive work. The CLI shuts down the agent on SIGINT or SIGTERM.

If startup times out, check the WebSocket URL, approval status, token, and active canonical model mapping. Use the inference API host for `/providers/ws`, not an unrelated web app host.

## Send a test request

Create an inference preset for the canonical model and an inference API key in the web app. Follow the [inference user guide](/consumers) to send a request using that preset ID.

Your provider must be connected and offer a valid quote to be considered. A request can select another provider, so receiving a successful response alone does not prove that your provider won. Check your engine activity or observe `onAward` as described in [Lifecycle and caching](/providers/lifecycle).

Next, adapt the [pricing and admission policy](/providers/policies) to your engine. For all configuration options and embedding functions, see the [SDK reference](/providers/sdk-reference).