# Installation

> Install @ontosdk/next: scaffold, add your site key and the build step, and check agents get Markdown.

Source: https://docs.buildonto.dev/sdk/installation
Section: Serve SDK

---

Installation\[01\]

## Installation

`@ontosdk/next` turns every prerendered page of your Next.js site into Markdown at build time, and hands it to agents at the edge. About five minutes.

### Install

\[02\]

1.  01
    
    ### Install the package
    
    npm, pnpm or yarn — whichever your project uses.
    
    
    ```
    npm install @ontosdk/next
    ```
    
2.  02
    
    ### Scaffold it
    
    Writes `onto.config.ts`, `middleware.ts` and `.env.local`, and leaves alone any that already exist.
    
    
    ```
    npx onto-next init
    ```
    
3.  03
    
    ### Add your site key
    
    From [Serve](https://app.buildonto.dev/serve/dashboard) once your domain is registered. The name is `ONTO_API_KEY`, the value is the site's `onto_live_` key — a Read key is refused. Without one the pages still build; they just don't reach your dashboard.
    
    text.env.localCopy
    
    ```
    ONTO_API_KEY=onto_live_YOUR_SITE_KEY
    ```
    
4.  04
    
    ### Add the build step
    
    After `next build`, the CLI writes a `.md` of every prerendered page into `public/.onto/`, plus `llms.txt`.
    
    jsonpackage.jsonCopy
    
    ```
    "scripts": {
      "build": "next build && onto-next"
    }
    ```
    
5.  05
    
    ### Build and deploy
    
    Deploy as you normally do.
    
    
    ```
    npm run build
    ```
    
6.  ✓
    
    It works when
    
    A request with an agent's user-agent comes back as Markdown, with Onto's headers on it.
    
    
    ```
    curl -sI -A 'GPTBot/1.0' https://yoursite.com/pricing
    
    # Content-Type: text/markdown; charset=utf-8
    # X-Onto-Bot: GPTBot (OpenAI)
    # X-Onto-Matched: true
    ```
    
    It worked
    
    It didn’t work
    
    **Still HTML?** Only prerendered pages get a `.md`; anything rendered per request falls back to HTML. Otherwise the build step didn't run, or the middleware's `matcher` skips the route.
    
    **“Control Plane sync skipped: Invalid API Key”?** That's a Read key in `ONTO_API_KEY` — use the site key.
    
    **Key set but not picked up?** The build CLI reads `.env.local` only; a real environment variable wins over it.
    

### Requirements

\[03\]

NeedsWhy

Next.js14 or later, App RouterThe CLI reads the App Router's `.next/server/app` output.

React18 or 19For the optional OntoProvider and OntoHead components.

Version1.6.7Pulls in `@ontosdk/core`, the same cleaner the Read API uses.

**Keep the key server-side.** Never prefix it `NEXT_PUBLIC_` — the middleware and the build CLI are the only things that read it.

Copy as Markdown[](/sdk/installation.md "Open the raw Markdown")

---
## Structured Data (JSON-LD)
```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Onto Docs",
  "url": "https://docs.buildonto.dev",
  "description": "How to use Onto: serve AI agents Markdown from your Next.js site, call the Read API, connect over MCP, and read the AIO score.",
  "inLanguage": "en",
  "publisher": {
    "@type": "Organization",
    "name": "Onto",
    "url": "https://buildonto.dev"
  }
}
```