Orazaka 101: Developer Onboarding Guide

Welcome to Orazaka! This 10-minute onboarding guide will help you understand what Orazaka is, how to get it running on your machine, and how to execute your first AI interactions.

1. Introduction

Orazaka is a self-hosted, local-first AI orchestration platform. It is designed to give you the power of cloud-based AI providers (like OpenAI or Anthropic) completely on your own hardware.

Whether you are building a chat application, generating images, or creating autonomous agents, Orazaka provides a unified API and a stunning user interface to manage it all.

2. Why Orazaka?

• Total Privacy (Local-First): All inference runs locally (using Ollama, Apple Metal MPS, or CUDA). No data ever leaves your machine.
• Multi-Modal Unified Engine: A single platform for Chat, Image Generation, Audio Transcription, and Video Synthesis.
• Production-Ready: Built on Java 21, Spring Boot, and Next.js, meaning it's ready for enterprise scale.
• Offline Resiliency: Work offline without issues. Agent commands are queued locally and executed when resources are available.

3. Simplified Architecture

Understanding how Orazaka works at a high level is simple:

1. The Clients (Next.js + Expo): You interact via the web client (port 3000), the admin console (port 3001), or the Expo mobile app (port 8081). All clients live under orazaka-apps/orazaka-ui/ as npm workspaces and proxy traffic through Next.js server-side API routes (BFF pattern).
2. The Brain (Gateway & Core): The clients talk to the Java backend (port 8080). This backend manages security, routing, and the orchestration of your AI tasks through a 15-stage interceptor pipeline.
3. The Muscles (Workers & Models): The backend delegates the heavy lifting to local AI models (via Ollama) and background workers (for heavy tasks like video rendering).

4. Installation

Getting Orazaka running is designed to be frictionless.

Prerequisites

• Java 21
• Node.js 24+
• Python 3.11+
• Ollama (installed and running locally)
• Docker (for databases and queues like PostgreSQL, Redis, RabbitMQ)

Setup Steps

1. Interactive Setup:

   bash

   Copy

   npx orazaka install
   

   (Detects hardware, verifies prerequisites, configures topology, and generates .env).

2. Start Infrastructure:

   bash

   Copy

   npx orazaka start
   

   (Boots PostgreSQL, Redis, RabbitMQ, Ollama, and LocalAI. Does not start application services).

3. Launch the Full Development Stack:

   bash

   Copy

   npx orazaka dev
   

   (Parallel-spawns the Router (BFF), Web Client, Admin Console, and Expo Mobile App with color-coded output).

   For finer control, launch a subset with --only (allow-list, comma-separated) or exclude with --skip-*:

   bash

   Copy

   npx orazaka dev --only mobile        # just the Expo server
   npx orazaka dev --only web,core      # web client + Router only
   

   Convenience scripts from orazaka-apps/orazaka-ui/: npm run dev:web · dev:admin · dev:mobile · dev:core.

Verifying a Clone-and-Run (onboard)

For a fresh checkout, run the production-readiness validator. It executes sequentially and never blocks the shell — every probe is timeout-guarded:

npx orazaka onboard

5. Quick Start: Your First Interactions

Once the infrastructure is running, you can interact with Orazaka via the UI or the CLI.

Option A: Using the UI (Recommended)

Open your browser and navigate to http://localhost:3000. Create an account, log in, and navigate to the Playgrounds to start chatting or generating images!

Default local dev accounts (seeded by infra/init.sql, local phase only — change before any non-local environment):

Role	Email	Password
Admin	admin@orazaka.com	Admin123!
User	user@orazaka.com	User1234!

Option B: Using the CLI

You can run commands directly from your terminal:

1. Your First Chat:

npx orazaka chat --prompt "Hello Orazaka! What can you do?"

2. Your First Agent Task:

npx orazaka agent run --task "Summarize the contents of my current directory."

3. Your First Image Generation:

npx orazaka image generate --prompt "A cyberpunk city at night, highly detailed, 4k"

6. Core Concepts

As you dive deeper into Orazaka, you'll encounter a few key concepts:

• Agents & Personas: AI instances with specific system prompts (saved as Markdown files) and access to specific tools.
• Workflows: Multi-step processes that chain together different models (e.g., Generate a script with an LLM -> Generate audio for the script -> Generate video matching the audio).
• Tools (MCP): Functions that your agents can call to interact with the outside world (like reading a file, searching the web, or querying a database).
• The Interceptor Chain: Every prompt you send passes through a series of "filters" (Interceptors) that enrich the prompt with context, validate it, and route it to the right model.

7. Next Steps

Now that you're up and running, here is where you should go next:

• Business Playbook: Learn how to build a product on Orazaka (CinePulse case study).
• UI Reference: Explore all the features of the Next.js frontend.
• Architecture Reference: Dive deep into the Hexagonal Architecture and the Interceptor Chain.
• CLI Reference: Complete command-line interface guide.
• Model Catalog: See which models are supported for text, vision, video, and audio.