Knowledge Hub

Quick Start

Get OpenFrame OSS Tenant running locally in a few steps. This guide focuses on getting the codebase cloned, built, and introduced to the key components.

TL;DR — 5-Minute Setup

# 1. Clone the repository
git clone https://github.com/flamingo-stack/openframe-oss-tenant.git
cd openframe-oss-tenant

# 2. Build all backend services (Java / Spring Boot)
mvn clean install -DskipTests

# 3. Install frontend dependencies (openframe-chat desktop app)
cd clients/openframe-chat
npm install

# 4. Build the Rust agent
cd ../openframe-client
cargo build

# 5. Return to root
cd ../..

Step 1 — Clone the Repository

git clone https://github.com/flamingo-stack/openframe-oss-tenant.git
cd openframe-oss-tenant

The repository has the following top-level structure:

openframe-oss-tenant/
├── openframe/
│   └── services/              # Spring Boot microservices
│       ├── openframe-api/     # Core REST + GraphQL API
│       ├── openframe-gateway/ # Spring Cloud Gateway
│       ├── openframe-authorization-server/
│       ├── openframe-client/  # Agent lifecycle service (Java)
│       ├── openframe-stream/  # Kafka Streams service
│       ├── openframe-management/
│       └── openframe-external-api/
├── clients/
│   ├── openframe-client/      # Rust cross-platform agent
│   └── openframe-chat/        # Tauri + React desktop app (Fae)
├── manifests/                 # Kubernetes manifests & data service configs
└── pom.xml                    # Parent Maven POM

Step 2 — Build the Backend (Spring Boot Services)

The backend is a Maven multi-module project. Build all services from the root:

mvn clean install -DskipTests

To run tests during the build:

mvn clean install

To build a single service (for example, the API service):

mvn clean install -pl openframe/services/openframe-api -am -DskipTests

Java 21 is required. Verify with java -version before building.

Step 3 — Build the Rust Agent (openframe-client)

cd clients/openframe-client
cargo build

For a release build:

cargo build --release

The compiled binary will be at target/debug/openframe-client (or target/release/openframe-client for release builds).

Step 4 — Install and Run the Desktop App (openframe-chat)

The openframe-chat desktop app uses React 19 + Vite for the frontend and Tauri 2 with a Rust backend.

cd clients/openframe-chat

# Install Node.js dependencies
npm install

# Start in development mode (hot reload)
npm run tauri dev

Tauri prerequisites (system libraries for WebView) must be installed first. See Prerequisites for platform-specific instructions.

Expected Output

When the Tauri development server starts successfully, you should see output similar to:

   VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3003/
  ➜  Network: use --host to expose

[tauri] Running application...

The OpenFrame Chat desktop window will launch automatically.

Frontend Build Only (No Tauri)

If you only need to work on the React frontend without running the Tauri shell:

cd clients/openframe-chat
npm run dev

This starts the Vite dev server at http://localhost:3003.

Verify the Rust Agent CLI

After building the agent, check its available commands:

./clients/openframe-client/target/debug/openframe-client --help

You should see:

Usage: openframe-client <COMMAND>

Commands:
  install    Install the agent as a system service
  uninstall  Remove the installed system service
  run        Run the client directly
  doctor     Run environment health checks
  help       Print this message or help for subcommands

Development Environment Variable

When running the Rust agent locally, set OPENFRAME_DEV_MODE to use local directories and disable TLS certificate verification:

OPENFRAME_DEV_MODE=1 ./target/debug/openframe-client run

Next Steps

With the codebase built, you can now:

• Review First Steps to explore key platform features
• Read the Architecture Overview to understand how services communicate
• Set up your Development Environment for a full IDE-based workflow