k9x_studio

Visual Architecture Builder for K9-AIF Systems

k9x_studio is a browser-based drag-and-drop IDE for designing K9-AIF multi-agent systems. It reads the k9_aif_abb component library, lets architects compose systems visually on a canvas, and generates production-ready YAML configuration and Python scaffold — the same output as k9_generator.sh, but designed rather than typed.

Try it live: studio.k9x.ai

Installation

Recommended:

pip install k9x

Then start the studio:

k9x studio

This opens a browser tab at http://localhost:12999 by default. Useful flags:

k9x studio --port 8080          # use a different port
k9x studio --bg                 # run in the background, return immediately
k9x studio --stop               # stop a background instance
k9x config                      # write a starter .env with LLM provider settings
k9x satan                       # start K9X Satan, the adversarial red-team harness
k9x upgrade                     # pip install --upgrade k9x

Run k9x help for the full command list. See LLM Configuration below for connecting a local or hosted model — the studio runs in demo mode without one.

Workflow

1. Project Setup
   └── Name, author, domain, description

2. Canvas Design (drag-and-drop)
   ├── Palette (left): Router, Orchestrator, Squad, Agent, ...
   ├── Canvas (center): drop nodes, draw connections
   └── Inspector (right): configure selected node

3. Generate Architecture  (LLM-powered when configured)
   └── AI suggests Orchestrators, Squads, and Agents based on description

4. Export Scaffold
   └── Downloads ZIP: config/ + agents/ + squads/ + Python stubs
       OR writes directly to k9_projects/<AppName>/

LLM Configuration

LLM is optional but strongly recommended. Without it the studio works in demo mode — templates and manual canvas composition are fully functional, but the Generate Architecture button produces a generic fallback instead of an AI-tailored suggestion.

Why configure an LLM?

• Generate Architecture uses the LLM to suggest Orchestrators, Squads, and Agents suited to your project description
• BPMN import (complex diagrams) uses the LLM to intelligently group flat tasks into meaningful Squads

Recommended approach — run LLM locally

Install Ollama on your own machine or server and pull a model:

ollama pull granite3-dense:2b   # fast, good JSON output
# or
ollama pull llama3.1:8b         # higher quality suggestions

Then point the studio at your Ollama endpoint. Your data never leaves your environment.

Supported providers

Note: localhost and 127.0.0.1 are intentionally blocked on the hosted instance at studio.k9x.ai to prevent the server's own resources from being used. Always use an IP address or hostname when configuring the endpoint.

Recommended models

Configuration methods

The studio checks LLM config in this priority order:

1. .env file — recommended for self-hosted deployments

Copy .env.sample to .env and fill in your values:

cp .env.sample .env

# .env
LLM_PROVIDER=ollama
LLM_ENDPOINT=http://10.0.0.5:11434
LLM_MODEL=granite3-dense:2b
LLM_API_KEY=                        # leave blank for Ollama

The .env file is loaded automatically on startup and is excluded from source control.

2. Environment variables (Docker / Podman -e flags)

podman run -d --name k9x_studio -p 8080:8080 \
  -e LLM_PROVIDER=ollama \
  -e LLM_ENDPOINT=http://10.0.0.5:11434 \
  -e LLM_MODEL=granite3-dense:2b \
  -e K9X_PROJECTS_ROOT="/k9x/projects" \
  -v ~/k9x-studio-working:/k9x/projects:Z \
  ghcr.io/k9aif/k9x-studio:latest

3. config.yaml (file-based, alternative to .env)

Edit config.yaml in the studio root before starting:

llm:
  enabled: true
  provider: ollama
  endpoint: "http://10.0.0.5:11434"
  model: granite3-dense:2b
  api_key: ""

4. Browser UI (session-only, transient)

Click ⬡ LLM Config at the bottom of the left panel. Enter endpoint, model, and optional API key. Config is held in your browser session only — it is not stored and clears on page refresh. Ideal for one-off use on a shared or public instance.

Running locally

cd k9x_studio

# 1. Configure your environment (first time only)
cp .env.sample .env
# Edit .env — add your LLM endpoint, API keys, and any other external config

# 2. Start
./run.sh          # starts backend (port 8080) + frontend dev server (port 5173)

.env is gitignored and never committed. All secrets stay local to your machine.

Or pull and run the container:

podman pull ghcr.io/k9aif/k9x-studio:latest
podman run -d --name k9x_studio -p 8080:8080 \
  -e K9X_PROJECTS_ROOT="/k9x/projects" \
  -v ~/k9x-studio-working:/k9x/projects:Z \
  ghcr.io/k9aif/k9x-studio:latest

Architecture

┌──────────┐    ┌────────────────────────────────────────────┐    ┌────────────────┐
│          │    │                  CANVAS                     │    │   INSPECTOR    │
│ PALETTE  │    │                                             │    │                │
│          │    │  [Router]────►[Orchestrator]                │    │ Node: Agent    │
│ Router   │    │                    │                        │    │ Name: FraudDet │
│ Orch.    │    │              [ClaimsSquad]                  │    │ Model: reason  │
│ Squad    │    │              ┌─────┴──────┐                 │    │ Pattern: loop  │
│ Agent    │    │          [Triage]  [Fraud] [Audit]          │    │ Role: ...      │
│ ValLoop  │    │                                             │    │                │
│ CritAct  │    │                                             │    │                │
│ Guard    │    │                                             │    │                │
└──────────┘    └────────────────────────────────────────────┘    └────────────────┘

Component Palette → ABB Mapping

Tech Stack

References

• K9-AIF Framework: github.com/k9aif/k9-aif-framework
• Studio container: ghcr.io/k9aif/k9x-studio:latest
• Live demo: studio.k9x.ai
• Ecosystem: k9x.ai/ecosystem

studiox