Quick Start

This guide walks you through creating a Kinotic App, defining an entity, generating its repository, and using the repository to read and write data.

Prerequisites

• Bun -- Install from https://bun.sh
• A Kinotic account with a linked GitHub organization

Create Your Application

Kinotic OS creates your Application and Project and provisions a GitHub repository for it, already scaffolded as a Bun workspace with the Kinotic CLI vendored as a dev dependency -- there is nothing to install globally.

The fastest way is the official Claude Code plugin, which drives the whole flow conversationally:

/plugin marketplace add kinotic-ai/claude-plugin
/plugin install kinotic@kinotic
/kinotic:new-app my-app

You can also create the Application and Project from the Kinotic OS dashboard; either way you end up with a provisioned repository.

Clone and Install

git clone <your-provisioned-repo> && cd <your-repo>
bun install

The repository comes with a .config/kinotic.config.ts already wired to your organization, application, and project, pointing entity discovery at packages/domain/model and repository generation at packages/domain/repositories.

Define an Entity

Create a file at packages/domain/model/Person.ts:

import { Entity, AutoGeneratedId, NotNull, Precision, PrecisionType, MultiTenancyType } from '@kinotic-ai/persistence'

@Entity(MultiTenancyType.NONE)
export class Person {
    @AutoGeneratedId
    id: string | null = null

    @NotNull
    firstName: string = ''

    @NotNull
    lastName: string = ''

    @Precision(PrecisionType.SHORT)
    age: number = 0
}

A few things to note:

• @Entity(MultiTenancyType.NONE) marks the class as a persisted entity with no multi-tenancy.
• @AutoGeneratedId tells the platform to generate an ID when one is not provided.
• @NotNull enforces that a field must have a value.
• @Precision(PrecisionType.SHORT) tells the platform this number is a short integer, which influences how it is stored and indexed.

Generate the Repository

bun run generate
bun run type-check

This writes packages/domain/repositories/PersonRepository.ts (yours to extend) along with a generated base class, and saves the entity's schema under .config/c3/. Export both from the domain package's entry so other packages can import them:

// packages/domain/index.ts
export * from './model/Person.js'
export * from './repositories/PersonRepository.js'

Push to Sync

git add . && git commit -m "Add Person entity" && git push

Kinotic OS reads entity definitions from the connected GitHub repository and synchronizes them for you -- publishing the entity creates the backing storage and registers its services. There is nothing to log in to or push from your machine besides git.

Use the Generated Repository

The provisioned repository ships a starter microservice at packages/microservices/main that already sets the zone and connects. Extend its src/main.ts to try the repository out:

import { Kinotic, Pageable } from '@kinotic-ai/core'
import { PersistencePlugin } from '@kinotic-ai/persistence'
import { PersonRepository } from '@my-app/domain'
import { appZone } from '@kinotic-ai/management-api'
import config from '../../../../.config/kinotic.config'

Kinotic.use(PersistencePlugin)
Kinotic.zonePrefix = appZone(config.organizationId, config.applicationId)

// server and credentials resolve from the environment: KINOTIC_SERVER_HOST/PORT/USE_SSL,
// KINOTIC_CLIENT_ID/KINOTIC_CLIENT_SECRET — https://api.kinotic.ai when nothing is set
await Kinotic.connect()

const personRepository = new PersonRepository()

// Create a person
const person = await personRepository.save({
    id: null,
    firstName: 'Jane',
    lastName: 'Doe',
    age: 28
})

console.log('Saved:', person)

// Find all people
const page = await personRepository.findAll(Pageable.create(0, 10))
console.log('People:', page.content)

Run it with Bun:

bun run packages/microservices/main/src/main.ts

You should see the saved person printed to the console, followed by a page of results containing that person.

What's Next?

Now that you have a working application, explore the rest of the documentation:

• Application Structure -- Understand how organizations, applications, projects, and artifacts are organized.
• Services -- Learn how to publish and consume services across your application.
• Persistence -- Dive deeper into entity definitions, relationships, and querying.