Part 5 — Studio
Complete walkthrough of HiveFlow Studio — the self-hosted ops UI.
5.1 Start Studio
Docker (easiest)
docker compose up --build
| URL |
Purpose |
| http://localhost:3000 |
React frontend |
| http://localhost:8000 |
FastAPI backend |
| http://localhost:8000/docs |
OpenAPI Swagger |
Local dev (two terminals)
# Terminal 1 — backend
cd packages/studio/backend
pip install -r requirements.txt
export HIVEFLOW_RUNTIME=agent
export HIVEFLOW_AGENT_ECHO_LLM=true
export HIVEFLOW_PLAN_HITL=true
uvicorn app.main:app --reload --port 8000
# Terminal 2 — frontend
cd packages/studio/frontend
npm install && npm run dev
5.2 Golden Path — Agent mode
- Open Orchestrator.
- Toggle Agent / real mode in the toolbar.
- Enter a goal: Summarize three trends in AI agents.
- Click Plan only — review the generated TaskGraph.
- Click Import to canvas.
- Click Execute DAG.
With HIVEFLOW_PLAN_HITL=true, step 4 creates a gate at Approvals before execution.
Deep dive: Studio Agent Mode cookbook.
5.3 Studio pages reference
| Page |
Purpose |
| Dashboard |
System overview, recent activity |
| Orchestrator |
DAG canvas, Agent drawer, plan/execute |
| Chatflow |
Conversational flow builder; Agent mode runs ai_reply nodes via run_query |
| Agents |
Register and configure agents |
| Approvals |
HITL gates — approve/reject/edit plan JSON |
| Blackboard |
Inspect shared keys in real time |
| Analytics |
Execution metrics, success rates |
| Tracer |
Live WebSocket trace (intent_id, trace_id) |
| Replay |
Audit log + checkpoint replay by intent_id |
| Events |
Event bus history |
| Knowledge Base |
RAG document management |
| LLM Config |
Provider keys and routing |
| Capability Market |
MCP plugin install/uninstall |
| Triggers |
Schedule and webhook triggers |
| Variables |
Environment and workflow variables |
| Prompt Templates |
Reusable prompt library |
| A/B Testing |
Compare prompt/model variants |
| Audit Log |
Compliance trail |
| Settings |
Studio configuration |
5.4 Key HTTP APIs
| Endpoint |
Method |
Purpose |
/api/agent/query |
POST |
NL query → plan → execute |
/api/agent/plan-only |
POST |
Generate plan JSON only |
/api/agent/execute-plan |
POST |
Execute existing plan graph |
/api/agent/export-langgraph |
POST |
Export canvas to LangGraph |
/api/workflows/* |
* |
Core DAG CRUD + execute |
/api/hitl/* |
* |
Approval gates |
/api/blackboard/* |
* |
Read/write shared state |
/api/analytics/* |
* |
Metrics (real mode) |
/api/replay/* |
* |
Checkpoint replay |
Full reference: API Reference.
5.5 Environment variables
| Variable |
Effect |
HIVEFLOW_RUNTIME=agent |
Default to Agent runtime |
HIVEFLOW_AGENT_ECHO_LLM=true |
Mock LLM (no API key) |
HIVEFLOW_PLAN_HITL=true |
Plan approval before execute |
HIVEFLOW_LLM_PLANNING_PROVIDER |
Planning LLM route |
HIVEFLOW_LLM_EXECUTION_PROVIDER |
Execution LLM route |
OPENAI_API_KEY / ANTHROPIC_API_KEY |
Real LLM providers |
5.6 Chatflow vs Orchestrator
| Feature |
Orchestrator |
Chatflow |
| Layout |
Free-form DAG canvas |
Conversation-oriented graph |
| Best for |
Batch pipelines, ETL, multi-step jobs |
Chatbots, Q&A flows |
| Agent mode |
plan-only → canvas → execute |
Topological ai_reply nodes |
5.7 Troubleshooting Studio
| Symptom |
Fix |
| Blank canvas after plan-only |
Check browser console; verify /api/agent/plan-only 200 |
| Execute does nothing |
Ensure Agent / real mode is on |
| No LLM response |
Set HIVEFLOW_AGENT_ECHO_LLM=true or provide API keys |
| WS disconnect on Tracer |
Confirm backend on :8000; check CORS / proxy |
| Approvals empty |
Enable HIVEFLOW_PLAN_HITL=true and run plan-only first |
See Studio Agent Operations.
5.8 Exercises
- Complete Golden Path with a custom goal and export LangGraph JSON.
- Reject a plan in Approvals, edit JSON, re-submit.
- Open Blackboard during execution and watch keys update live.
Next
→ Part 6 — Production: deploy, monitor, maintain.