Skip to content
ont-run

Quick Start

ont-run supports both TypeScript and Go backends. Choose your preferred language below.

Installation

Terminal window
# TypeScript backend (default)
npx ont-run init my-api


# Go backend
npx ont-run init-go my-api

TypeScript Quick Start

1. Initialize project

Terminal window
npx ont-run init my-api
cd my-api

2. Create your ontology

The generated ontology.config.ts defines your API:

import { defineOntology, z } from 'ont-run';
import healthCheck from './resolvers/healthCheck.js';
import getUser from './resolvers/getUser.js';


export default defineOntology({
  name: 'my-api',


  accessGroups: {
    public: { description: 'Unauthenticated users' },
    user: { description: 'Authenticated users' },
    admin: { description: 'Administrators' },
  },


  entities: {
    User: { description: 'A user account' },
  },


  functions: {
    healthCheck: {
      description: 'Check API health status',
      access: ['public', 'user', 'admin'],
      entities: [],
      inputs: z.object({}),
      outputs: z.object({ status: z.string() }),
      resolver: healthCheck,
    },


    getUser: {
      description: 'Get user details by ID',
      access: ['user', 'admin'],
      entities: ['User'],
      inputs: z.object({ userId: z.string().uuid() }),
      outputs: z.object({
        id: z.string(),
        name: z.string(),
        email: z.string(),
      }),
      resolver: getUser,
    },
  },
});

3. Create a resolver

Create resolvers/getUser.ts:

import type { ResolverContext } from 'ont-run';


export default async function getUser(
  ctx: ResolverContext,
  args: { userId: string }
) {
  ctx.logger.info(`Getting user: ${args.userId}`);
  return {
    id: args.userId,
    name: 'Example User',
    email: 'user@example.com',
  };
}

4. Start the server

Terminal window
npm run dev

This starts the REST API at http://localhost:3000 and MCP server for AI integration.

5. Review ontology changes

Terminal window
npx ont-run review

Go Quick Start

1. Initialize project

Terminal window
npx ont-run init-go my-api
cd my-api/backend

2. Define your ontology

Edit ontology.config.go:

package main


import (
    ont "github.com/vanna-ai/ont-run/pkg/ontology"
    "myapp/resolvers"
)


func DefineOntology() *ont.Config {
    return &ont.Config{
        Name:  "my-api",
        UUID:  "your-uuid-here",  // Generated by init
        Cloud: true,              // Enable cloud registration


        AccessGroups: map[string]ont.AccessGroup{
            "public": {Description: "Unauthenticated users"},
            "user":   {Description: "Authenticated users"},
            "admin":  {Description: "Administrators"},
        },


        Entities: map[string]ont.Entity{
            "User": {Description: "A user account"},
        },


        Functions: map[string]ont.Function{
            "healthCheck": {
                Description: "Check API health status",
                Access:      []string{"public", "user", "admin"},
                Entities:    []string{},
                Inputs:      ont.Object(map[string]ont.Schema{}),
                Outputs:     ont.Object(map[string]ont.Schema{
                    "status": ont.String(),
                }),
                Resolver: resolvers.HealthCheck,
            },
            "getUser": {
                Description: "Get user details by ID",
                Access:      []string{"user", "admin"},
                Entities:    []string{"User"},
                Inputs:      ont.Object(map[string]ont.Schema{
                    "userId": ont.String().UUID(),
                }),
                Outputs:     ont.Object(map[string]ont.Schema{
                    "id":    ont.String(),
                    "name":  ont.String(),
                    "email": ont.String().Email(),
                }),
                Resolver: resolvers.GetUser,
            },
        },
    }
}

3. Create a resolver

Create resolvers/get_user.go:

package resolvers


import (
    ont "github.com/vanna-ai/ont-run/pkg/ontology"
)


func GetUser(ctx ont.Context, input any) (any, error) {
    args := input.(map[string]any)
    userID := args["userId"].(string)


    ctx.Logger().Info("Getting user", "userId", userID)


    return map[string]any{
        "id":    userID,
        "name":  "Example User",
        "email": "user@example.com",
    }, nil
}

4. Start the server

main.go
package main


import (
    "log"
    ont "github.com/vanna-ai/ont-run/pkg/ontology"
    "github.com/vanna-ai/ont-run/pkg/server"
)


func main() {
    ontology := DefineOntology()


    if err := ontology.Validate(); err != nil {
        log.Fatalf("Invalid ontology: %v", err)
    }


    // Auto-generate lock and SDK in dev mode
    ontology.WriteLock("../ont.lock")


    log.Println("Starting server on :8080")
    server.Serve(ontology, ":8080", server.WithLogger(ont.ConsoleLogger()))
}

Run:

Terminal window
go run .

The server:

  • Generates ont.lock automatically
  • Generates TypeScript SDK to ../frontend/src/sdk/
  • Starts REST API at http://localhost:8080
  • Registers with ont-run.com (if Cloud enabled)

Next steps