# What Is the Main Entry Point for Agent-Native? (BuilderIO/agent-native)

> Discover the main entry point for Agent-Native. Learn how the createServer function from @agent-native/core initializes your H3 server with essential middleware for seamless development.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: getting-started
- Published: 2026-06-21

---

**The main entry point for agent-native is the `createServer` function exported from the `@agent-native/core` package, which initializes a pre-configured H3 server with built-in CORS, health checks, and authentication middleware.**

The `agent-native` framework from BuilderIO provides a structured way to build AI-powered applications. Understanding the main entry point is essential for developers integrating the library into Node.js servers or desktop environments. This guide identifies the exact source files and demonstrates how to bootstrap your first agent-native server using the core entry point.

## The Core Entry Point: `createServer`

The heart of the framework resides in the **`createServer`** function. This utility, defined in [`packages/core/src/server/create-server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/create-server.ts), constructs an H3 server instance pre-wired with essential middleware for production-ready agent applications.

The function accepts a configuration object supporting parameters like **`cors`**, **`pingMessage`**, and **`envKeys`**. It returns an object containing the **`app`** (the H3 instance) and **`router`** for defining custom routes.

## Export Chain and File Structure

Understanding the module hierarchy clarifies how the entry point surfaces in your codebase.

### Server Implementation Layer

The concrete implementation lives at **[`packages/core/src/server/create-server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/create-server.ts)**. This file handles low-level concerns including CORS headers, health-check endpoints (`/ping`), environment variable validation routes, and authentication middleware setup.

### Package Barrel Exports

The function propagates upward through two barrel files:
- **[`packages/core/src/server/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/index.ts)** – Re-exports `createServer` alongside server-specific utilities like `upsertEnvFile` and body-reading helpers.
- **[`packages/core/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/index.ts)** – The primary public API of `@agent-native/core` that exposes `createServer` together with the complete framework surface (agents, actions, widgets).

### Compiled Output Entry

After running `pnpm build`, the root [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json) field `"main": "index.js"` points to the compiled artifact. This generated file forwards to the transpiled version of [`packages/core/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/index.ts), ensuring `require("@agent-native/core")` resolves correctly to the main entry point.

## Practical Implementation Examples

### Minimal Server Setup

Create a basic server with CORS enabled and environment key validation:

```typescript
// src/server.ts
import { createServer } from "@agent-native/core";

const { app, router } = createServer({
  cors: true,
  pingMessage: "pong",
  envKeys: [
    { key: "MY_API_TOKEN", label: "My API Token", required: true },
  ],
});

export default app; // Nuxt/Nitro consumes this H3 app

```

### Adding Custom Routes

Extend the router with application-specific endpoints:

```typescript
import { createServer } from "@agent-native/core";

const { app, router } = createServer();

router.get("/hello", (event) => {
  return { message: "Hello from agent-native!" };
});

export default app;

```

### Desktop Application Integration

Use the same entry point in Vite-powered desktop environments:

```typescript
import { createServer } from "@agent-native/core";

async function startDesktop() {
  const { app, router } = createServer({ cors: false });
  // Mount the H3 app on an Electron or Vite dev server
}

```

## Summary

- The **main entry point** for agent-native is the **`createServer`** function from `@agent-native/core`.
- Source implementation resides in **[`packages/core/src/server/create-server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/create-server.ts)**.
- The function is re-exported through **[`packages/core/src/server/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/index.ts)** and **[`packages/core/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/index.ts)**.
- It returns an **`app`** (H3 instance) and **`router`** for handling HTTP requests.
- Configuration options include **`cors`**, **`pingMessage`**, and **`envKeys`** for environment variable validation.

## Frequently Asked Questions

### What does the `createServer` function return?

The `createServer` function returns an object containing two properties: **`app`**, which is the configured H3 server instance ready for mounting, and **`router`**, which provides the routing interface for defining your application's endpoints.

### Where is the `createServer` function defined in the source code?

According to the BuilderIO/agent-native repository, the function is implemented in **[`packages/core/src/server/create-server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/create-server.ts)**. It is then re-exported through the barrel files at [`packages/core/src/server/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/index.ts) and [`packages/core/src/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/index.ts) for public consumption.

### Can I use agent-native without the `createServer` wrapper?

While you could theoretically construct an H3 server manually, `createServer` is the supported entry point because it automatically configures critical middleware for CORS, health checks, and environment variable management that agent-native applications expect.

### How do I configure CORS and environment variables when starting the server?

Pass a configuration object to `createServer` with the **`cors`** boolean flag and an **`envKeys`** array. Each object in `envKeys` should specify the `key`, human-readable `label`, and whether it is `required`, which creates automatic validation routes for your application's environment setup.