🚀 Orchestrate ADK Studio

A Cross-Platform Desktop App for Managing Your IBM watsonx Orchestrate AI Agents, Tools, and Workflows

A native desktop experience for IBM watsonx Orchestrate development

Features • Download • Quick Start • Usage • Development

🎯 The Problem We Solve

The IBM watsonx Orchestrate Agent Development Kit (ADK) is incredibly powerful, offering CLI utilities and Python modules to build, test, and deploy AI agents. However, working exclusively with the command line can be:

Time-consuming — Running multiple commands to get an overview of your resources
Error-prone — Manually typing complex commands with flags and parameters
Lacking visibility — No unified view of agents, tools, toolkits, and their relationships
Difficult to compare — Hard to see configurations side-by-side across environments
Not collaborative — Team members need CLI expertise to contribute

Orchestrate ADK Studio bridges this gap as a native desktop application that provides a visual, intuitive interface while preserving all the power of the underlying CLI. Available for macOS, Windows, and Linux.

✨ Why Use the Dashboard?

CLI vs Dashboard Comparison

Task	Using CLI	Using Dashboard
List all agents	`orchestrate agents list`	One click, instant overview with filters
View agent details	`orchestrate agents list -v` → parse JSON	Click to expand, see tools, collaborators, config
Check all resources	Run 4+ separate commands	Single dashboard view with live counts
Switch environments	`orchestrate env activate <name>`	One-click environment switching
Find a specific tool	`orchestrate tools list \| grep <name>`	Real-time search with instant results
Import from repo	Navigate + `orchestrate agents import -f`	Browse repos, select components, one-click import
Test an agent	Write test scripts or use API	Built-in chat with thread history
Compare configurations	Manual file comparison	Cross-environment diff with unified & side-by-side views

Key Benefits

🎨 Visual Resource Management — See all your agents, tools, toolkits, connections, knowledge bases, and models at a glance

⚡ 10x Faster Workflows — What takes 5 CLI commands happens in one click

🔄 Smart Caching — 5-minute cache with background refresh reduces API calls

🌓 Modern UI/UX — Dark/light mode, responsive design, beautiful animations

📊 Unified Dashboard — Resource distribution charts, quick stats, CLI reference

🔌 Multi-Environment Support — Easily manage local, IBM Cloud, AWS, and on-premises deployments

🔍 Powerful Search & Filters — Find any resource instantly across your entire workspace

📁 Repository Import — Browse local repositories and import agents, tools, toolkits with dependency resolution

💬 Agent Chat — Test agents interactively with thread-based conversations and chat history

📤 Smart Export — Export agents and tools with automatic dependency bundling and repository integration

🌟 Features

Core Features

📊 Dashboard Overview
- Real-time resource counts (Agents, Tools, Toolkits, Connections, Knowledge Bases, Models)
- Visual resource distribution charts
- Quick actions for common tasks
- CLI command reference with syntax highlighting
🤖 Agent Management
- List and search all agents
- View detailed configurations, tools, and collaborators
- Deploy/undeploy agents between draft and live states
- View agent channels and chat history
🔧 Tools & Toolkits
- Browse all available tools with type indicators (Python, OpenAPI, MCP, Flow)
- Explore toolkit contents and MCP configurations
- View input/output schemas and connection requirements
- Filter by toolkit, type, or search
� Agentic Flows
- View agentic workflows deployed in your environment
- Interactive DAG visualization with nodes and edges
- Zoom in/out with auto-fit and drag-to-pan
- Theme-aware rendering (light/dark mode)
- Full-screen modal with two-panel layout
- Inspect steps: tools, agents, branches, loops, and more
- Export flow definitions as JSON
- Cross-environment flow comparison
- CLI command reference for flow import/export
�🔗 Connections
- Manage API connections and credentials
- View connection status and configurations
- Support for OAuth, API Key, Bearer, and Basic auth types
📚 Knowledge Bases
- Manage RAG-enabled knowledge bases
- View vector index configurations
- Monitor indexing status and document counts
🧠 Models
- Browse available LLM chat models
- View model IDs, tags, and lifecycle information
- Identify recommended models
🌍 Environment Management
- Add, edit, and remove Orchestrate environments
- One-click environment switching
- Support for local, IBM IAM, MCSP, and CPD deployments
- Secure API key storage
🔁 Environment Transfer
- Move agents, tools, flows, toolkits, and connections between environments
- Step-by-step wizard with validation and conflict detection
- Detailed transfer logs and history tracking
📦 Repository Import
- Browse local repositories for ADK components
- Smart dependency detection and resolution
- Batch import with proper ordering
- Support for agents, tools, toolkits, and connections
💬 Agent Chat
- Test agents with interactive chat interface
- Thread-based conversation continuity
- Per-agent chat history stored locally
- Resume previous conversations anytime
- View model and thread information
- Support for both cloud and local Developer Edition environments
🖥️ Developer Edition Server
- Integrated local server management from Settings
- Start/stop local Orchestrate server (port 4321)
- Automatic environment file configuration
- Server status monitoring with health checks
- Configure API keys and entitlements directly in UI
- Seamless switching between cloud and local environments
📤 CLI Export
- Export agents and tools with full dependency bundling
- Automatic CLI environment synchronization
- ZIP extraction with folder structure flattening
- Auto-add exported folder as repository
🔍 Cross-Environment Compare
- Compare any agent, tool, toolkit, or connection across environments
- Side-by-side and unified diff views with color-coded changes
- Smart normalization strips environment-specific fields (IDs, timestamps, etc.)
- One-click compare from any resource detail panel
📡 Observability Dashboard
- Comprehensive monitoring of all operations (API calls, CLI commands, navigation, config changes)
- Per-environment event tracking with automatic capture via global fetch interceptor
- IndexedDB storage (via Dexie.js) for practically unlimited capacity — no more localStorage quota errors
- Smart body truncation (50 KB cap) preserving top-level structure with truncation markers
- Configurable retention policy (default 7 days) with automatic purge on startup
- Automatic one-time migration from localStorage to IndexedDB on upgrade
- Detailed event inspection with request/response bodies, headers, timings, and error details
- Stats overview with total operations, success/error counts, average duration, and error rate
- Category breakdown with visual progress bars (API, CLI, Navigation, Auth, Data, Config, System)
- Filterable, sortable data table with search, multi-filter by status/category/method, and tabs (All/Errors/Bookmarked)
- Event detail slide-over with Overview, Request, Response, Logs, and Error tabs
- Bookmarking, export to JSON, and configurable capture settings
- Sensitive header redaction (Authorization, API keys) for security

UI/UX Features

🌓 Dark/Light Mode — System-aware theme with manual toggle
📱 Responsive Design — Works on desktop, tablet, and mobile
⚡ Optimistic Updates — Instant UI feedback with background sync
🎨 Modern Animations — Smooth transitions with Framer Motion
🔔 Toast Notifications — Real-time feedback for all actions
📋 One-Click Copy — Copy IDs, commands, and configurations easily
⚙️ Settings Page — Theme preferences, cache management, and Developer Edition configuration
🔄 Auto-Updates — Seamless updates with GitHub Enterprise authentication
📡 Observability — Monitor all operations with detailed request/response inspection

� Download

Pre-built Binaries

Download the latest release (v1.1.6) for your platform:

Platform	Download
macOS (Apple Silicon)	Orchestrate ADK Studio-1.1.6-arm64.dmg
macOS (Intel)	Orchestrate ADK Studio-1.1.6.dmg
Windows	Coming Soon
Linux	Coming Soon

Latest Release: v1.1.6 - Agentic Flows with interactive DAG visualization, zoom controls, and theme-aware rendering

View All Releases

🚀 Quick Start

Option 1: Run the Desktop App

Download and install the app for your platform (see above)
Launch Orchestrate ADK Studio
Navigate to Environments and add your Orchestrate instance
Start managing your agents, tools, and workflows!

Option 2: Run from Source (Development)

Prerequisites

Node.js 18.x or higher
npm, yarn, pnpm, or bun
IBM watsonx Orchestrate environment with API access
ADK CLI (optional, for advanced operations)

Installation

Clone the repository

git clone git@github.ibm.com:kirtijha/orchestrate-adk-studio.git
cd orchestrate-adk-studio

Install dependencies
```
npm install
```

Start the desktop app in development mode

npm run electron:dev

Or run as a web app:

npm run dev
# Open http://localhost:3000

First-Time Setup

Launch the app and navigate to Settings from the sidebar
Enter your Orchestrate ADK server URL and API key
Click Connect — this creates your local environment automatically
Return to the Dashboard to browse agents, tools, toolkits, and connections

Adding More Environments

Once your local environment is connected, you can add additional environments (staging, production, etc.):

Navigate to Environments from the sidebar
Click Add Environment and enter:
- Name: A friendly name (e.g., "Production", "Staging")
- URL: Your Orchestrate API endpoint
- Type: Select deployment type (ibm_iam, mcsp, or cpd)
- API Key: Your authentication key
Click Connect to activate the environment
Switch between environments using the environment selector in the header

Local Developer Edition

In Settings, scroll to the Developer Edition section
Configure your local server:
- Source: Select myibm or license_key
- Instance URL: Your watsonx Orchestrate instance URL
- API Key: Your watsonx API key (base64 encoded)
- Entitlement Key: Your IBM Cloud Pak entitlement key (for license_key source)
Click Start Server to launch the local Orchestrate server
The server will be available at http://localhost:4321

📖 Usage

Dashboard Navigation

Section	Description
Dashboard	Overview with stats, quick actions, and CLI reference
Agents	Manage AI agents, view configurations, deploy/undeploy
Chat	Test agents with interactive conversations and thread history
Tools	Browse and search all available tools
Toolkits	Explore MCP toolkits and their tools
Connections	Manage API connections and credentials
Knowledge Bases	RAG knowledge base management
Models	Available LLM models for your agents
Channels	Generate webchat embeds for your agents
Repositories	Browse and manage local ADK repositories
Environments	Add and switch between Orchestrate environments
Transfer	Move components between environments with validation
Import	Import components from local repositories
Observability	Monitor all operations with full request/response details
Settings	Theme, cache settings, and Developer Edition server
About	Version info, architecture, and helpful links

Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd + K`	Open command palette
`Ctrl/Cmd + /`	Toggle sidebar
`Escape`	Close modals and panels

Environment Variables (Optional)

Create a .env.local file for default configurations:

# Default Orchestrate endpoint (optional)
NEXT_PUBLIC_DEFAULT_ORCHESTRATE_URL=http://localhost:4321

# Enable debug logging
NEXT_PUBLIC_DEBUG=false

Note: For Developer Edition server management, API keys and configuration are managed through the Settings page in the application. The app automatically creates and manages the environment file at ~/Library/Application Support/orchestrate-adk-studio/orchestrate.env.

🏗️ Architecture

orchestrate-adk-studio/
├── electron/
│   └── main.js                 # Electron main process
│                                 # - Window management
│                                 # - IPC handlers
│                                 # - Developer Edition server lifecycle
│                                 # - Auto-updater with GHE authentication
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/
│   │   │   ├── orchestrate/    # API routes (proxy to Orchestrate)
│   │   │   ├── filesystem/     # File system operations
│   │   │   └── repositories/   # Repository management
│   │   └── dashboard/          # Dashboard pages
│   │       ├── agents/         # Agent management
│   │       ├── chat/           # Agent chat interface
│   │       ├── observability/  # Observability monitoring
│   │       ├── settings/       # App & Developer Edition settings
│   │       ├── channels/       # Webchat embed generator
│   │       └── ...             # Other resource pages
│   ├── components/             # Reusable UI components
│   │   ├── ui/                 # shadcn/ui components
│   │   └── dashboard/          # Dashboard-specific components
│   │       ├── agent-chat.tsx  # Chat interface component
│   │       ├── import-wizard.tsx
│   │       └── ...             # Other dashboard components
│   ├── lib/                    # Utilities and hooks
│   │   ├── hooks/              # Custom React hooks
│   │   ├── store/              # Zustand state management
│   │   │   ├── developer-edition-store.ts
│   │   │   ├── observability-store.ts
│   │   │   └── ...             # Other stores
│   │   ├── orchestrate/        # Orchestrate API client
│   │   ├── observability/      # Observability IndexedDB layer & interceptors
│   │   ├── security/           # API key obfuscation (base64)
│   │   └── performance/        # Caching utilities
│   └── types/                  # TypeScript type definitions
├── public/                     # Static assets
└── package.json

Tech Stack

Technology	Purpose
Electron 40	Cross-platform desktop framework
Next.js 16	React framework with App Router
React 19	UI library with Server Components
TypeScript	Type-safe development
Tailwind CSS 4	Utility-first styling
shadcn/ui	High-quality UI components
Zustand	Lightweight state management
Dexie.js	Type-safe IndexedDB wrapper
Framer Motion	Smooth animations
Lucide React	Beautiful icons

📦 Building & Distribution

Build the Desktop App

# Build for macOS (both Intel and Apple Silicon)
npm run electron:build

# The installers will be in dist-electron/

Build Output

File	Platform	Description
`Orchestrate ADK Studio-x.x.x-arm64.dmg`	macOS Apple Silicon	DMG installer for M1/M2/M3 Macs
`Orchestrate ADK Studio-x.x.x.dmg`	macOS Intel	DMG installer for Intel Macs
`*.zip`	macOS	ZIP archive (for auto-updates)
`*.blockmap`	macOS	Delta update files

Sharing the Installer

Option 1: GitHub Releases (Recommended)

# Tag the release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# Upload .dmg files to GitHub Releases via web UI

Option 2: Direct File Sharing

Upload the .dmg files to Google Drive, Dropbox, IBM Box, or internal file servers.

Option 3: Internal Artifact Repository

Upload to Artifactory, Nexus, or similar internal artifact repository.

Repackaging After Updates

# 1. Make your code changes

# 2. Update version in package.json
npm version patch   # 1.0.0 → 1.0.1 (bug fixes)
npm version minor   # 1.0.0 → 1.1.0 (new features)
npm version major   # 1.0.0 → 2.0.0 (breaking changes)

# 3. Rebuild the installer
npm run electron:build

# 4. New installers in dist-electron/

Auto-Update Options

The app has built-in auto-update support using electron-updater. When a new version is available on GitHub Releases, users will be prompted to download and install it.

How Auto-Update Works

On app launch, it checks GitHub Releases for new versions
If an update is available, a dialog prompts the user
User can download the update (with progress bar)
After download, user can restart to apply the update
Users can also manually check via Help → Check for Updates...

GitHub Enterprise Authentication: The app automatically reads your GitHub token from the gh CLI using gh auth token --hostname github.ibm.com, so no manual token configuration is needed if you have the GitHub CLI installed and authenticated.

Publishing a Release

# 1. Update version
npm version patch   # 1.0.0 → 1.0.1

# 2. Ensure gh CLI is authenticated
gh auth status --hostname github.ibm.com

# 3. Build the app
npm run electron:build:mac

# 4. Create release and upload assets
gh release create v1.x.x dist-electron/*.dmg dist-electron/*.zip dist-electron/*.blockmap dist-electron/latest-mac.yml \
  --repo github.ibm.com/kirtijha/orchestrate-adk-studio \
  --title "Orchestrate ADK Studio v1.x.x" \
  --notes "Release notes here"

Note: For IBM GitHub Enterprise (github.ibm.com), you need the GitHub CLI (gh) installed and authenticated with a Personal Access Token that has repo scope.

Creating a GitHub Personal Access Token

Go to github.ibm.com → Settings → Developer settings → Personal access tokens
Generate a new token with repo scope
Copy the token and use it as GH_TOKEN

Manual Release (Alternative)

If you prefer not to use auto-publish:

# 1. Build the app
npm run electron:build

# 2. Create a release on GitHub manually
# 3. Upload the .dmg, .zip, and .blockmap files from dist-electron/
# 4. Make sure to include the latest.yml file for auto-updates

Building for Other Platforms

# Windows (requires Windows or Wine on macOS/Linux)
npm run electron:build -- --win

# Linux (requires Linux or Docker)
npm run electron:build -- --linux

# All platforms
npm run electron:build -- --mac --win --linux

🆕 Recent Improvements

v1.1.6 (February 2026)

✅ Agentic Flows Visualization: Full-featured flow diagram rendering
- Interactive DAG visualization with topological sort layout
- Zoom in/out controls (30%–200%) with auto-fit on load
- Drag-to-pan and directional pan buttons (↑←→↓)
- Theme-aware rendering — proper colors for both light and dark modes
- Full-screen dialog modal (95vw × 90vh) with two-panel layout
- Node types: Start, End, Tool, Agent, Branch, ForEach, Loop, Prompt, Script, User Flow
- Edge condition labels, hover glow effects, and bezier curve connections
- Flow stats summary bar with node composition breakdown
- Cross-environment flow comparison
- CLI-based flow model export with auto environment sync
- Flow instances listing with status tracking

v1.1.5 (February 2026)

✅ IndexedDB Storage for Observability: Migrated event storage from localStorage to IndexedDB
- Eliminates QuotaExceededError — IndexedDB supports GBs vs localStorage's 5–10 MB limit
- Smart body truncation (50 KB cap) preserves top-level structure with __truncated markers
- Configurable retention policy (default 7 days) with automatic purge on startup
- Automatic one-time migration from localStorage on upgrade — zero data loss
- Events persisted to IndexedDB in background; settings remain in lightweight localStorage (~200 B)
- Added Dexie.js for type-safe, performant IndexedDB access

v1.1.4 (February 2026)

✅ Observability Dashboard: Comprehensive monitoring for all operations
- Global fetch interceptor auto-captures all API calls with full request/response
- Per-environment event storage with configurable limits (100–1000 events)
- Stats cards: total operations, success/error counts, avg duration, error rate
- Category breakdown with visual progress bars
- Filterable, sortable table with search, multi-filter, and tabs (All/Errors/Bookmarked)
- Detail slide-over with Overview, Request, Response, Logs, and Error tabs
- Bookmarking, JSON export, sensitive header redaction
- Header badge with live error count
- Environment switch tracking

v1.1.3 (February 2026)

✅ Cross-Environment Compare: Compare any resource across environments
- Side-by-side and unified diff views with LCS-based diff algorithm
- Smart normalization strips IDs, timestamps, and environment-specific metadata
- Available for agents, tools, toolkits, and connections
- Color-coded additions, deletions, and unchanged lines

v1.1.2 (February 2026)

✅ Critical Bug Fix: Fixed API key corruption in Developer Edition settings
- Replaced AES-256-CBC encryption with base64 encoding for browser compatibility
- API keys no longer lose characters when stored in localStorage
- Maintains backward compatibility with legacy format

v1.1.1 (February 2026)

✅ Auto-Update Fix: GitHub Enterprise authentication now works seamlessly
- Automatically reads token from gh CLI
- No manual token configuration needed

v1.1.0 (February 2026)

✅ CLI PATH Resolution: Fixed all CLI command execution paths
- Agents, tools, toolkits, connections, transfer, import, export all working
- Proper PATH resolution in Electron environment

Key Features Added Since v1.0.0

✅ Integrated Developer Edition server management
✅ Agent chat with thread history
✅ Webchat embed code generator
✅ Settings page with theme and cache controls
✅ Auto-update support for GitHub Enterprise
✅ Secure API key storage with obfuscation
✅ IndexedDB-backed observability with automatic data retention

🗺️ Roadmap

Current Version (v1.1.6)

✅ Dashboard with resource overview
✅ Agent, Tool, Toolkit, Connection management
✅ Knowledge Base and Models support
✅ Multi-environment management
✅ Repository import with dependency resolution
✅ Smart caching with auto-sync
✅ Dark/Light mode
✅ Agent Chat — Test agents with thread-based conversations
✅ Developer Edition — Integrated local server management
✅ Auto-Updates — GitHub Enterprise support with authentication
✅ Webchat Embed Generator — Create webchat embeds for agents
✅ Settings Page — Theme, cache, and Developer Edition configuration
✅ Cross-Environment Compare — Diff any resource across environments with side-by-side views
✅ Observability Dashboard — Monitor all operations with full request/response, per-environment event tracking, and detailed inspection
✅ IndexedDB Storage — Production-grade observability storage with retention policies and body truncation
✅ Agentic Flows — Interactive DAG visualization with zoom, pan, theme-aware rendering, and full-screen modal

Coming Soon (v1.2.0)

🔜 Agent Builder — Visual agent creation wizard
🔜 Tool Builder — Create Python/OpenAPI tools visually
🔜 Bulk Operations — Select multiple resources for batch actions

Future Plans

📋 Agentic Workflow Designer — Visual flow builder for complex workflows
📊 Analytics Dashboard — Usage metrics and performance insights
🔄 Git Integration — Direct sync with Git repositories
👥 Team Collaboration — Shared workspaces and access control
🧪 Test Runner — Run agent tests from the UI
📦 Marketplace — Discover and share community agents and tools

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Use Tailwind CSS for styling
Write meaningful commit messages
Test across light and dark modes
Ensure responsive design

📚 Resources

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

IBM watsonx Orchestrate team for the powerful ADK
Vercel for Next.js and deployment platform
shadcn for the beautiful UI components
The open-source community

Built with ❤️ for the IBM watsonx Orchestrate community

A native desktop experience powered by Electron + Next.js

Report Bug • Request Feature • Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
electron		electron
public		public
scripts		scripts
src		src
.gitignore		.gitignore
ENHANCEMENT_PLAN.md		ENHANCEMENT_PLAN.md
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_v1.0.0.md		RELEASE_NOTES_v1.0.0.md
components.json		components.json
electron-builder.json		electron-builder.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation