Orkee

A CLI, TUI, dashboard, and native desktop app for AI agent orchestration

Features

• 🤖 AI Agent Orchestration - Deploy and manage AI agents across different environments
• 🎯 Customizable AI Models - Configure different AI providers and models for each task type (chat, PRD generation, insight extraction, etc.)
• 📦 AI-Powered Sandboxes - Isolated execution environments with multi-provider support (Docker, Beam, E2B, Modal, Fly.io, and more)
• 📊 Real-time Dashboard - Web-based interface for monitoring and management
• 🖥️ Terminal Interface - Rich TUI for interactive command-line workflows
• 🖼️ Native Desktop App - Tauri-based desktop application with system tray integration
• 🔧 CLI Tools - Command-line interface for configuration and control
• 🔗 Workflow Coordination - Orchestrate complex multi-agent workflows
• 🔐 Enterprise Security - OAuth authentication, JWT validation, and Row Level Security
• 🔒 HTTPS/TLS Support - Secure connections with auto-generated or custom certificates
• 💾 Local-First Architecture - SQLite-based storage for fast, reliable data management

Project Structure

This is a Turborepo monorepo containing:

orkee/
├── packages/
│   ├── cli/          # Rust Axum HTTP server providing REST API endpoints
│   ├── dashboard/    # React SPA with Vite, Shadcn/ui, and Tailwind CSS
│   │   └── src-tauri/    # Tauri desktop app wrapper with system tray
│   ├── tui/          # Ratatui-based standalone terminal interface
│   ├── projects/     # Shared Rust library for core functionality (used by CLI and TUI)
│   ├── preview/      # Development server management with registry
│   ├── agents/       # AI agent registry and definitions
│   ├── sandbox/      # Sandbox infrastructure with multi-provider support
│   └── mcp-server/   # MCP (Model Context Protocol) server for Claude integration
├── deployment/       # Production deployment configurations
└── scripts/          # Build and release automation scripts

Architecture

Orkee provides multiple interfaces for AI agent orchestration:

• CLI Server - REST API backend (default port 4001, configurable)
• Dashboard - React web interface (default port 5173, configurable)
• Desktop App - Native Tauri application with system tray (bundles CLI server as sidecar)
• TUI - Standalone terminal interface with rich interactive features
• Projects Library - Core SQLite-based project management (used by CLI and TUI)
• Preview Library - Development server management with central registry

The Dashboard and Desktop App require the CLI server to be running. The TUI works independently.

Installation

Option 1: Desktop App (Native GUI + CLI + TUI) - v0.0.9 (Recommended)

Download the native desktop application for your platform:

macOS

• Apple Silicon: Orkee_0.0.9_aarch64.dmg (12 MB)
• Intel: Orkee_0.0.9_x64.dmg (12 MB)

Installation (IMPORTANT):

1. Double-click the .dmg file and drag Orkee to your Applications folder
2. Remove quarantine attributes (REQUIRED):

   sudo xattr -cr /Applications/Orkee.app

   This command is necessary because the app is unsigned. macOS Gatekeeper will block the app without this step.
3. Launch Orkee from Applications folder or Spotlight

Windows

• Installer (recommended): Orkee_0.0.9_x64_en-US.msi (10 MB)
• Setup EXE: Orkee_0.0.9_x64-setup.exe (7 MB)

Installation: Download and run the installer. You may see a Windows SmartScreen warning - click "More info" and then "Run anyway" (app is unsigned).

Linux

• Debian/Ubuntu: Orkee_0.0.9_amd64.deb (12 MB)

  sudo dpkg -i Orkee_0.0.9_amd64.deb

• Fedora/RHEL: Orkee-0.0.9-1.x86_64.rpm (12 MB)

  sudo rpm -i Orkee-0.0.9-1.x86_64.rpm

• Universal (AppImage): Orkee_0.0.9_amd64.AppImage (86 MB)

  chmod +x Orkee_0.0.9_amd64.AppImage
  ./Orkee_0.0.9_amd64.AppImage

The desktop app includes:

• 🖥️ Native desktop application with system tray
• 💻 Full CLI access (orkee command)
• 🎨 Terminal UI (orkee tui)
• 🌐 Web dashboard in native window

View all releases | Checksums

Option 2: npm (CLI + TUI + Web Dashboard)

# Install globally via npm
npm install -g orkee

# Verify installation
orkee --version

# Start the dashboard
orkee dashboard

# Or use the terminal interface
orkee tui

The npm package automatically downloads the appropriate binary for your platform (macOS, Linux, Windows).

Option 3: Build from Source

git clone https://github.com/OrkeeAI/orkee.git
cd orkee
bun install
turbo build

Quick Start

# Install dependencies
bun install

# Choose your interface:

# 1. Native Desktop App with system tray (recommended)
turbo dev:tauri

# 2. Web-based dashboard
turbo dev                    # Start both CLI server and dashboard
turbo dev:web               # Alternative: web-only development

# 3. CLI + Dashboard (manual)
cargo run --bin orkee -- dashboard                      # Default ports: API 4001, UI 5173
cargo run --bin orkee -- dashboard --api-port 8080 --ui-port 3000  # Custom ports
ORKEE_API_PORT=9000 ORKEE_UI_PORT=3333 cargo run --bin orkee -- dashboard  # Via env vars

# 4. Terminal interface (standalone, no server required)
cargo run --bin orkee -- tui

# Explore CLI capabilities
cargo run --bin orkee -- --help

Enable HTTPS (Optional)

# Create .env file and enable TLS
echo "TLS_ENABLED=true" > .env

# Start with HTTPS (auto-generates development certificates)
cargo run --bin orkee -- dashboard

# Dashboard will be available at https://localhost:4001
# HTTP requests to port 4000 automatically redirect to HTTPS

AI Provider Authentication

Orkee supports authentication with AI providers, allowing you to use your subscription accounts instead of API keys.

Benefits

• ✅ Use Claude Pro/Max subscriptions - No API costs, leverage your existing subscription
• ✅ Secure token management - Encrypted storage in local SQLite database
• ✅ Simple setup - Import tokens generated by provider CLIs
• ✅ Backward compatible - Works alongside existing API key authentication

Quick Setup (Claude)

# Authenticate with Claude (uses Claude CLI to generate token)
orkee auth login claude

# Or import a token from file
orkee auth login claude --file ~/claude-token.txt

# Check authentication status
orkee auth status

# Logout from a provider
orkee auth logout claude

# Logout from all providers
orkee auth logout all

Supported Providers

Provider	Status	Implementation
Claude (Anthropic)	✅ Available	Token import via Claude CLI
OpenAI	⏳ Planned	OAuth flow
Google (Vertex AI)	⏳ Planned	OAuth flow
xAI (Grok)	⏳ Planned	OAuth flow
Docker Hub	✅ Available	Docker CLI wrapper

How Claude Authentication Works

1. Login: Run orkee auth login claude to import a token
2. Token generation: The Claude CLI (claude setup-token) opens your browser for authentication
3. Token import: Orkee captures and imports the generated OAuth token
4. Token storage: Tokens are encrypted and stored in ~/.orkee/orkee.db
5. Use in apps: Dashboard and CLI use the token transparently

Token Characteristics:

• Format: sk-ant-oat01-... (OAuth Access Token)
• Validity: 1 year from creation
• Refresh: Not supported - re-authenticate when expired

Security Considerations

⚠️ IMPORTANT: By default, Orkee uses machine-based encryption which provides transport encryption only.

With machine-based encryption:

• ✅ Tokens are protected during backup/sync operations
• ❌ Anyone with access to ~/.orkee/orkee.db on your machine can decrypt the tokens
• ❌ This is NOT true at-rest encryption

For production use or shared machines, upgrade to password-based encryption:

orkee security set-password    # Enable password-based encryption
orkee security status          # Check current encryption mode

Password-based encryption provides:

• ✅ True at-rest encryption - tokens cannot be decrypted without your password
• ✅ Suitable for shared machines and production environments
• ⚠️ Password cannot be recovered if lost

Prerequisites

Claude CLI Required: The Claude authentication flow requires the Claude CLI to be installed:

# Install Claude CLI (requires Node.js)
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Migration from API Keys

Orkee maintains full backward compatibility with API keys stored in Settings. You can use both authentication methods simultaneously:

# Check current authentication status
orkee auth status

# Add Claude OAuth token alongside existing API keys
orkee auth login claude

# Your API keys in Settings continue to work as before
# OAuth tokens and API keys can coexist

Dashboard Integration

Authentication status can be viewed in the dashboard:

1. Navigate to Settings → Authentication
2. View authentication status for all providers
3. See token expiry times
4. Manage authentication via CLI commands

Docker Authentication

Orkee provides simple Docker Hub authentication for building and pushing sandbox container images.

Quick Setup

# Authenticate with Docker Hub
orkee auth login docker

# Verify authentication
docker info  # Should show your username

How It Works

• Simple wrapper: Runs docker login as a subprocess
• Native credential storage: Docker CLI handles credentials in system keychain
• No database storage: Credentials managed by Docker, not Orkee
• Standard workflow: Use normal docker build and docker push commands

Benefits

• ✅ Simple: No custom credential management needed
• ✅ Secure: Leverages Docker's system keychain integration
• ✅ Standard: Uses Docker's native authentication flow
• ✅ Rate limits: Authenticated users get 200 pulls/6 hours vs 100 unauthenticated

Troubleshooting

If you encounter authentication errors:

1. Run orkee auth login docker
2. Follow Docker's authentication prompts
3. Verify credentials: docker info should display your username

For more details, see docker.md.

AI-Powered Sandboxes

Orkee provides isolated execution environments where AI agents can safely execute code and perform tasks.

Features

• 📦 Multi-Provider Support - Local Docker + 7 cloud providers (Beam, E2B, Modal, Fly.io, Cloudflare, Daytona, Northflank)
• 🤖 Agent Integration - Works with Claude, Codex, Gemini, Grok, and OpenCode agents
• 📊 Resource Monitoring - Real-time CPU, memory, disk, and network tracking
• 💰 Cost Tracking - Full token usage and cost calculation per execution
• 🔒 Security - Encrypted credentials, resource limits, non-root user enforcement
• 🎨 Terminal UI - Interactive terminal with xterm.js for command execution
• 📁 File Operations - Upload/download files to/from sandboxes
• ⚙️ Configurable - All settings managed via Dashboard UI

Quick Start

# Authenticate with Docker Hub (for local provider)
orkee auth login docker

# Set default sandbox image
orkee sandbox config set-image orkee/sandbox:latest

# Create a sandbox via CLI
orkee sandbox create --provider local --cpu 2 --memory 4096

# Or use the Dashboard UI
# Navigate to: Dashboard > Sandboxes > Create Sandbox

Sandbox Commands

# Sandbox Management
orkee sandbox list                              # List all sandboxes
orkee sandbox create [--provider] [--cpu] [--memory]  # Create sandbox
orkee sandbox start <id>                        # Start sandbox
orkee sandbox stop <id>                         # Stop sandbox
orkee sandbox restart <id>                      # Restart sandbox
orkee sandbox delete <id>                       # Delete sandbox
orkee sandbox exec <id> <command>               # Execute command
orkee sandbox logs <id> [--follow]              # View logs

# Image Management
orkee sandbox build <name> [--tag] [--dockerfile]  # Build custom image
orkee sandbox push <image>                         # Push to Docker Hub
orkee sandbox images                               # List built images

# Configuration
orkee sandbox config show                       # Show current settings
orkee sandbox config set-image <image>          # Set default image
orkee sandbox config set-username <name>        # Set Docker Hub username

For complete documentation, see sandboxes.md.

Desktop App (Tauri)

The Orkee Desktop App is a native application built with Tauri that provides:

Features

• 🎯 System Tray Integration - Native menu bar icon with live server monitoring
• 🔄 Automatic Server Management - Launches and manages the CLI server automatically
• 🌐 Quick Access - Open servers in browser directly from tray menu
• 📋 URL Copying - Copy server URLs to clipboard with one click
• ⚡ Server Controls - Start, stop, and restart development servers from the tray
• 🎨 Theme Adaptation - macOS template icons automatically adapt to light/dark mode
• 💻 Cross-Platform - Supports macOS, Windows, and Linux

System Tray Menu

The tray provides:

• Show Orkee Dashboard - Opens the main dashboard window
• Dev Servers - Lists all running development servers with:
  • Open in Browser
  • Copy URL
  • Restart Server
  • Stop Server
• Refresh - Manually refresh server list (also polls automatically every 5 seconds)
• Quit Orkee - Gracefully stops all servers and exits

Running the Desktop App

Development Mode

# Start the Tauri dev app (from repository root)
turbo dev:tauri

# Or from the dashboard directory
cd packages/dashboard
pnpm tauri dev

Production Build

# Build the desktop app for your platform
cd packages/dashboard
pnpm tauri build

# The built app will be in:
# - macOS: src-tauri/target/release/bundle/macos/
# - Windows: src-tauri/target/release/bundle/msi/
# - Linux: src-tauri/target/release/bundle/appimage/

Configuration

The desktop app supports the following environment variables:

# Customize tray polling interval (default: 5 seconds, min: 1, max: 60)
ORKEE_TRAY_POLL_INTERVAL_SECS=10

# UI port for the dashboard (default: 5173)
ORKEE_UI_PORT=3000

Background Operation

The desktop app is designed to run in the background:

• Closing the window hides the app to the system tray (it doesn't quit)
• Access the app via the menu bar/system tray icon
• Quit from the tray menu to fully exit and stop all servers
• macOS: Runs as an Accessory app (menu bar only, no Dock icon by default)

Note: The Tauri app bundles the Orkee CLI binary as a sidecar process. It will automatically start the API server on an available port when launched.

PRD Ideation & CCPM Workflow

Orkee provides AI-powered PRD (Product Requirements Document) ideation and Chat-Based Collaborative Project Management:

💡 Ideate → 📄 PRD → 📋 Epic → ✅ Tasks

Ideation Modes:

• 🚀 Quick Mode - Generate complete PRDs instantly from a description
• 🎯 Guided Mode - Step-by-step section building with AI assistance
• 📝 Template-Based - Use customizable templates for different project types

PRD Features:

• 📄 Structured Sections - Overview, UX, Technical, Roadmap, Dependencies, Risks, Research
• 🤖 AI-Powered Generation - Complete PRD generation or section-by-section expansion
• 💾 Version Tracking - Full PRD history with soft delete support
• 🎨 Custom Templates - Create and manage reusable PRD templates

CCPM (Chat-Based Collaborative Project Management):

• 💬 Epic Generation - Convert PRDs into actionable epics with AI
• 🔄 Iterative Refinement - Chat-based workflow for epic improvement
• 🎯 Task Decomposition - Break down epics into executable tasks
• 🔍 Research Tools - Competitor analysis, similar projects, and technical specs

AI Usage Tracking & Telemetry

Orkee provides comprehensive tracking of all AI operations, including token usage, costs, and tool invocations:

Features

• 📊 Automatic Tracking - All AI SDK calls are tracked automatically (zero manual logging required)
• 💰 Cost Monitoring - Real-time cost tracking across different AI providers and models
• 🔧 Tool Call Analytics - Track which tools are invoked, success rates, and performance
• 📈 Usage Dashboard - Visual analytics with charts for tokens, costs, and tool usage over time
• 🎯 Per-Operation Metrics - Track specific operations like PRD generation, chat responses, etc.

Tracked Metrics

For every AI operation, Orkee tracks:

• Tokens: Input, output, and total token counts
• Cost: Estimated cost based on provider pricing
• Duration: Actual request duration (not 0ms!)
• Tool Calls: Which tools were invoked, arguments, results, and success/failure
• Model/Provider: Which AI model and provider was used
• Metadata: Finish reason, response ID, and provider-specific metadata

Usage Dashboard

Access the Usage tab in the Orkee dashboard to view:

• Overview - Key metrics cards with totals for requests, tokens, costs, and tool calls
• Model Breakdown - Token usage distribution across different AI models
• Provider Breakdown - Cost distribution across providers (Anthropic, OpenAI, etc.)
• Tool Analytics - Most used tools with success rates and performance metrics
• Charts & Analytics - Time-series visualizations for requests, tokens, and costs

For Developers

All AI operations are automatically wrapped with telemetry tracking. When adding new AI functionality:

Using the telemetry wrapper:

import { trackAIOperation } from '@/lib/ai/telemetry';

// Wrap your AI SDK call
const result = await trackAIOperation(
  'operation_name',        // e.g., 'generate_prd', 'chat_response'
  projectId,               // Project ID or null for global operations
  () => generateText({     // Your AI SDK call
    model: anthropic('claude-3-opus'),
    prompt: 'Your prompt here',
    tools: { search, calculate }
  })
);

The wrapper automatically:

• Tracks token usage and costs
• Measures actual duration with high precision
• Extracts tool calls from responses
• Handles streaming responses via onFinish callback
• Sends telemetry to backend without blocking the operation
• Logs errors without breaking the AI operation

Tool call data structure:

interface ToolCall {
  name: string;                    // Tool name (e.g., 'search', 'calculate')
  arguments: Record<string, any>;  // Tool arguments
  result?: any;                    // Tool result (if available)
  durationMs?: number;             // Tool execution time
  error?: string;                  // Error message if tool failed
}

Architecture

• Frontend Telemetry - packages/dashboard/src/lib/ai/telemetry.ts wraps AI SDK calls
• Backend Endpoint - POST /api/ai-usage accepts telemetry data with validation
• Database Storage - SQLite table ai_usage_logs with full-text search support
• Analytics Endpoints - Stats, tool usage, and time-series data for charts

All telemetry is asynchronous to ensure zero performance impact on AI operations.

Documentation

• Configuration & Architecture - Complete development guide and architecture details
• Environment Variables & Configuration - Environment variables, security, and operational configuration
• Production Deployment - Docker, Nginx, TLS/SSL, and security setup
• Security Guidelines - Security policies and vulnerability reporting
• AI Usage Implementation Plan - Detailed implementation plan for AI tracking features

Development

Prerequisites

• Node.js (v18+) | Bun (v1.0+) | Rust (latest stable)

Quick Start

# Clone and install
git clone https://github.com/OrkeeAI/orkee.git
cd orkee && bun install

# Start development (all interfaces)
turbo dev                    # Web dashboard + CLI server
turbo dev:tauri              # Native desktop app

# Or start specific interfaces
cargo run --bin orkee -- dashboard --dev  # Web dashboard with hot reload
cargo run --bin orkee -- tui              # Terminal interface

Common Commands

turbo build                  # Build all packages
turbo test                   # Run all tests
turbo lint                   # Lint all packages
cargo test                   # Run Rust tests

For detailed development instructions, see CLAUDE.md

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT

Support

• 📖 Documentation
• 💬 Discussions
• 🐛 Issues

---

Made with ❤️ by the Orkee team