Skip to content
OwlLayerAI

Install

From zero to an agent-driven interface.

Four steps. One central server that talks to the model, one client in your interface. Your buttons, links and form fields become tools the agent executes.

Before you start

  • Node.js 22 or later
  • A package manager: pnpm, npm, yarn or bun
  • An API key from Google, OpenAI or Anthropic

One server, every client

Every client (React, Vue, Svelte, Angular or plain HTML) connects to the same OwlLayer AI Server over AITP. The server holds the model keys and runs the agent; your interface declares the tools and executes them.

Frontend

Model provider

Package manager

  1. 1

    Start the central server

    The server is the single endpoint every client connects to. It keeps your provider key out of the browser and talks to the model.

    mkdir my-owllayer-server && cd my-owllayer-server
    pnpm add @owllayer/server @owllayer/adapter-google dotenv

    Put the keys in a .env file next to server.ts.

    .env
    GOOGLE_API_KEY=your_provider_keyOWLLAYER_CLIENT_API_KEY=pk_dev_local
    server.ts
    import 'dotenv/config';import { OwlLayerServer } from '@owllayer/server';import { GoogleAdapter } from '@owllayer/adapter-google'; const server = new OwlLayerServer({  llm: new GoogleAdapter({    apiKey: process.env.GOOGLE_API_KEY!,    model: 'gemini-2.5-flash',    systemPrompt: 'You help the user act in the current interface.',  }),  port: 3000,  path: '/owllayer',}); // Every client (React, Vue, Svelte, Angular, HTML) connects with this key.server.addApiKey(process.env.OWLLAYER_CLIENT_API_KEY!); server.listen(() => console.log('OwlLayer AI on ws://localhost:3000/owllayer'));

    Start it: it listens on ws://localhost:3000/owllayer.

    pnpm dlx tsx server.ts
    Read the guide
  2. 2

    Connect your interface

    Install the SDK for your frontend and point it at the server endpoint, with the client key accepted by the server.

    New project? Scaffold one (skip this with an existing app).

    pnpm create vite my-client --template react-ts

    Add the SDK.

    pnpm add @owllayer/react @owllayer/core zod

    Connect once, at the root of the app.

    src/main.tsx
    import { OwlLayerProvider } from '@owllayer/react'; <OwlLayerProvider  apiKey="pk_dev_local"  endpoint="ws://localhost:3000/owllayer"  config={{ hitl: { ui: 'modal' } }}>  <App /></OwlLayerProvider>

    Start your app.

    pnpm dev
    Read the guide
  3. 3

    Turn a button into a tool

    Declare the tool on the element that owns the action. From now on, the agent can call it, with typed input, a risk level, and your own handler doing the work.

    src/AddToCart.tsx
    import { useAgentTool } from '@owllayer/react';import { z } from 'zod'; export function AddToCart({ product }) {  // This button is now a tool the agent can call.  useAgentTool(    {      name: 'add_to_cart',      description: 'Add the current product to the cart',      schema: z.object({ quantity: z.number().int().min(1) }),      risk: 'low',    },    async ({ quantity }) => cart.add(product, quantity),  );   return <button onClick={() => cart.add(product, 1)}>Add to cart</button>;}
    Read the guide
  4. 4

    Talk to the agent

    Open your app and ask, in text or voice:

    • "Add this product to my cart": the agent calls add_to_cart.
    • Mark a tool high or critical and the agent waits for your approval before it runs.
    • Navigate away: the tools of the previous screen disappear from the agent.

If something does not work

Connection refused
The server is not running or the endpoint differs. Start server.ts and check that the client uses exactly ws://localhost:3000/owllayer (same port and path).
Invalid client key
The apiKey in your client must be one the server accepts with server.addApiKey(…). Check OWLLAYER_CLIENT_API_KEY in .env.
The agent does not see my tool
The tool only exists while its element is on screen. Make sure the component is mounted inside the provider/plugin, and that tool names are unique.