Ontology-enforced API framework for AI coding agents
npm install ont-runVibe code with confidence.
A web framework designed for the era of coding agents. You define the ontology—what operations exist and who can perform them. AI writes the implementation.
https://github.com/user-attachments/assets/93fbf862-aca3-422d-8f0c-1fc1e4510d88
``typescript
// ontology.config.ts
import { defineOntology, z } from 'ont-run';
import getTicket from './resolvers/getTicket.js';
import assignTicket from './resolvers/assignTicket.js';
export default defineOntology({
name: 'support-desk',
accessGroups: {
public: { description: 'Unauthenticated users' },
support: { description: 'Support agents' },
admin: { description: 'Administrators' },
},
functions: {
getTicket: {
description: 'Get ticket details',
access: ['support', 'admin'],
entities: ['Ticket'],
inputs: z.object({ ticketId: z.string().uuid() }),
resolver: getTicket,
},
assignTicket: {
description: 'Assign ticket to an agent',
access: ['admin'], // If AI tries to add 'public' here, review is triggered
entities: ['Ticket'],
inputs: z.object({ ticketId: z.string().uuid(), assignee: z.string() }),
resolver: assignTicket,
},
},
// ...
});
`
Coding agents (Claude Code, Cursor, etc.) can edit resolver implementations freely. But changes to the ontology—functions, access groups, inputs—trigger a review that agents can't bypass. It's built into the framework.
| Layer | Contains | Who modifies |
|-------|----------|--------------|
| Ontology | Functions, access groups, inputs, entities | Humans only (via ont-run review) |
| Implementation | Resolver code | AI agents freely |
Your job shifts: instead of writing every line, you encode what the system can do and who can do it. You review a visual map of capabilities—not 7,000 lines of code.
If Claude tries to let public call assignTicket (currently admin-only):
1. The ontology config changes
2. ont.lock detects the mismatch
3. Server refuses to start
4. You review the visual diff and approve or reject
`
WARN Ontology has changed:
~ assignTicket
Access: [admin] -> [admin, public]
WARN Run npx ont-run review to approve these changes.`
Why not just prompts? The ontology is the source of truth. The framework won't run if it changes without human review.
`bash`
npx ont-run init my-api
This creates a new project with the ont-run framework configured.
`bash`
npx ont-run init my-api
cd my-api
`bash`
npm run review
Opens a browser showing all functions and access groups. Click Approve to generate ont.lock.
The generated project includes a full-stack setup with Vite + React Router for the frontend and Hono for the backend.
`bash`
npm run dev
Your API is running at http://localhost:3000.
Resolvers are where AI writes the implementation:
`typescript
// resolvers/assignTicket.ts
import type { ResolverContext } from 'ont-run';
export default async function assignTicket(
ctx: ResolverContext,
args: { ticketId: string; assignee: string }
) {
// AI can modify this freely—no review required
const ticket = await db.tickets.update({
where: { id: args.ticketId },
data: { assigneeId: args.assignee },
});
return { id: ticket.id, assignedTo: args.assignee };
}
`
The resolver context provides:
- ctx.env — Current environment namectx.envConfig
- — Environment configurationctx.logger
- — Logger instancectx.accessGroups
- — Access groups for the request
`typescript
import { defineOntology, z } from 'ont-run';
import getUser from './resolvers/getUser.js';
export default defineOntology({
name: 'my-api',
environments: {
dev: { debug: true },
prod: { debug: false },
},
// Auth returns access groups (and optional user identity)
auth: async (req: Request) => {
const token = req.headers.get('Authorization');
if (!token) return { groups: ['public'] };
const user = await verifyToken(token);
return {
groups: user.isAdmin ? ['admin', 'user', 'public'] : ['user', 'public'],
user: { id: user.id, email: user.email }, // Optional: for row-level access
};
},
accessGroups: {
public: { description: 'Unauthenticated users' },
user: { description: 'Authenticated users' },
admin: { description: 'Administrators' },
},
entities: {
User: { description: 'A user account' },
Ticket: { description: 'A support ticket' },
},
functions: {
getUser: {
description: 'Get user by ID',
access: ['user', 'admin'],
entities: ['User'],
inputs: z.object({ userId: z.string().uuid() }),
resolver: getUser,
},
},
});
`
The framework handles group-based access (user → group → function) out of the box. For row-level ownership (e.g., "users can only edit their own posts"), use userContext():
`typescript
import { defineOntology, userContext, z } from 'ont-run';
import editPost from './resolvers/editPost.js';
export default defineOntology({
// Auth must return user identity for userContext to work
auth: async (req) => {
const user = await verifyToken(req);
return {
groups: ['user'],
user: { id: user.id, email: user.email },
};
},
functions: {
editPost: {
description: 'Edit a post',
access: ['user', 'admin'],
entities: ['Post'],
inputs: z.object({
postId: z.string(),
title: z.string(),
// currentUser is injected at runtime, hidden from API callers
currentUser: userContext(z.object({
id: z.string(),
email: z.string(),
})),
}),
resolver: editPost,
},
},
});
`
In the resolver, you receive the typed user object:
`typescript
// resolvers/editPost.ts
export default async function editPost(
ctx: ResolverContext,
args: { postId: string; title: string; currentUser: { id: string; email: string } }
) {
const post = await db.posts.findById(args.postId);
// Row-level check: only author or admin can edit
if (args.currentUser.id !== post.authorId && !ctx.accessGroups.includes('admin')) {
throw new Error('Not authorized to edit this post');
}
return db.posts.update(args.postId, { title: args.title });
}
`
Key points:
- userContext() fields are injected from auth() result's user field
- They're hidden from public API/MCP schemas (callers don't see or provide them)
- They're type-safe in resolvers
- The review UI shows a badge for functions using user context
ont.lock is the enforcement mechanism. It contains a hash of your ontology:
What gets hashed (requires review):
- Function names and descriptions
- Access group assignments
- Input schemas
What doesn't get hashed (AI can change freely):
- Resolver implementations
- Environment configurations
- Auth function implementation
`bash`
npx ont-run init [dir] # Initialize a new project
npx ont-run review # Review and approve ontology changes
All functions are exposed as POST endpoints:
`bashCall a function
curl -X POST http://localhost:3000/api/getUser \
-H "Authorization: your-token" \
-H "Content-Type: application/json" \
-d '{"userId": "123e4567-e89b-12d3-a456-426614174000"}'
As the cost of software production trends toward the cost of compute, every business will encode itself as a software system—through autonomous agents and process orchestration.
ont-run is the enforcement layer that keeps AI agents aligned with your business rules as they automate your operations.
MIT