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

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, 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. 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 – Re-exports createServer alongside server-specific utilities like upsertEnvFile and body-reading helpers.
• 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 field "main": "index.js" points to the compiled artifact. This generated file forwards to the transpiled version of 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:

// 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:

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:

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.
• The function is re-exported through packages/core/src/server/index.ts and 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. It is then re-exported through the barrel files at packages/core/src/server/index.ts and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}