Installation

Prerequisites

• Bun ≥ 1.3 (bun --version)
• A terminal and a code editor

Install the package

Add the framework (ships the oke CLI):

bun add okengine

Scaffold with create-oke

Create the standard recommended project layout:

bunx create-oke@latest my-app
bunx create-oke@latest my-app --template standard
bunx create-oke@latest my-app --sql postgres

The standard template is the only starter. --sql postgres opts into a pgTable schema and pins local, Docker, and production to Postgres; the default keeps local SQLite with Docker and production on Postgres.

Run the app

cd my-app
oke dev

Local mode watches domain schema paths (schema.ts / schema.decl.ts / app.ts) and auto-runs oke db push (drizzle-kit) so the database stays in sync. Opt out with oke dev --no-db-push or db: { autoPush: false } in oke.config.ts. For production, generate and apply migrations deliberately:

oke db generate   # write drizzle/*.sql
oke db migrate    # apply — never automatic on boot

Three ports come up together (mnemonic: O·K·E = 6·5·3):

Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.

Want Postgres/Redis like production while the app stays on host Bun?

oke dev --docker   # or: oke dev -d
# or set the saved default: oke mode docker

That uses the docker driver profile in oke.config.ts (filled from prod when omitted). Compose files and credentials land under docker/ (.env.docker beside compose). Host ports — including Mailpit UI / RustFS console extras — are unique per project so multiple apps can run at once. Bare oke dev prompts once on a TTY (saved in .oke/mode); non-TTY defaults to local.

The generated env follows each protocol instead of forcing one generic credential shape:

• Postgres: DATABASE_URL plus OKE_STORE_SQL_*
• Redis: REDIS_URL plus OKE_STORE_KV_PASSWORD
• S3-compatible files: S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_URL, S3_REGION, and S3_CONSOLE_URL
• SMTP email: SMTP_URL, SMTP_HOST, SMTP_PORT, and MAILPIT_UI_URL with optional SMTP_USER / SMTP_PASSWORD

Each section also includes commented controls (for example Redis memory policy, Postgres init options, Bun S3 session tokens, and Mailpit limits). Uncommented supported controls are preserved when oke dev --docker regenerates the file.

Verify the install

Hit the app (path depends on the template) or open http://localhost:6533. If the Console lists your flows, the install worked.