MachinaOSMachinaOS
Guided Walkthrough · 5–8 min self-guided · 12 min with presenter

Demo Storyboard

Know exactly what to type, what to expect, and why each moment is worth pausing on. The sandbox runs a real MachinaOS instance on the Acme Web Platform seed workspace — all prompts below work out of the box.

Audience: developers, technical founders, PMs exploring AI-native tooling.
Sandbox model: GPT-4o-mini (cloud) — no setup, no key required.

Open the Demo → Demo Ground Rules
New — Sprint 86

Describe It, Build It.

The Neural Link now understands pipeline intent. Type a sentence — “Create a chain that checks for secrets and scans recent commits” — and MachinaOS builds a fully structured, versioned, executable workflow chain in seconds using the active LLM’s native tool-calling API. No config, no drag, no code. Or click ✨ Generate in Studio and watch the canvas populate automatically — parallel swim-lanes, conditional branches, agent assignments and all.

NL Chain Generation — from Neural Link, Studio ✨ Generate, or REST API — Act 6 → 🔗 Webhook Triggers — any CI/CD pipeline or external system can fire your chains via HMAC-signed HTTP POST — Act 7 →

What You Land On

Home Dashboard

Four health cards — Memory, LLM, Agent Fleet, Tools — plus a live event feed on the right and the workspace context panel showing Acme Web Platform.

The LLM status dot in the bottom bar should be green (GPT-4o-mini, connected). If it shows amber, wait 5 seconds and reload — the container may be warming up.

Orientation Overlay

A one-sentence welcome explains the read-only sandbox. Click Start Exploring to dismiss it.

The quick-prompts bar below the chat input shows 8 curated suggestions — any of them is a valid starting point. The walkthrough below follows a coherent narrative, but visitors can jump anywhere.

Act 1

"What's in this project?"

~2 min — Goal: show that MachinaOS understands the workspace and can answer questions about it without the user spelling out any commands.

1a

Open the Neural Link

Click the Chat tab in the nav (or press Ctrl+2).

Show me the project structure
What happens MachinaOS recognises a list intent heuristically — no LLM round-trip. It runs filesystem.tree on the seeded workspace and returns a formatted tree:
📁 Acme Web Platform
├── 📁 src/
│   ├── 📁 auth/
│   │   └── handler.py
│   └── 📁 api/
│       └── users.py
├── 📁 tests/
├── 📁 config/
└── README.md
Output arrives in under 2 seconds with no configuration. No CLI, no terminal, no remembered flag syntax.
1b

Read a Specific File

Read the authentication handler
What happens Intent is routed deterministically to filesystem.read_file. MachinaOS locates src/auth/handler.py and displays it with syntax highlighting. The response includes SECRET_KEY = "change-me-in-production" on line 11.
Pause here — point out that hardcoded secret. "Any developer reviewing this manually might miss it. Machina OS will find it automatically — we'll show that in Act 3."
1c

Ask a Natural-Language Question

What does this project do? Summarize it for me.
What happens Goes to the conversational LLM path. RAG context from the indexed workspace is injected — the reply references FastAPI, React, the auth module, and TODO items from README.md. Response streams token by token.
The model answers based on actual file content, not a generic guess. The event feed on the right shows tool_started → tool_finished events ticking in real time.
Act 2

"Tools, not chat"

~2 min — Goal: show the Tools view and demonstrate that MachinaOS is a system with real, typed tool invocations — not just a chatbot wrapper.

2a

Open the Tools View

Click Tools in the nav (Ctrl+3). The grid shows 52 registered tools across 9 domains: filesystem, git, shell, system, process, browser, vscode, productivity.

Hover over filesystem.grep. A rich tooltip shows the tool name, description, risk level badge (MEDIUM), and parameter list. Click Use — the chat input pre-fills with filesystem.grep.

"Every tool is a first-class citizen with a typed schema. Nothing is hidden inside the LLM."
2b

Run a Tool Directly

Search for TODO comments in the project
What happens Routes to filesystem.grep with query="TODO". Returns grouped results by file:
📄 README.md
  L14: - [ ] Payment integration
  L15: - [ ] Admin dashboard
📄 src/auth/handler.py
  L3: # TODO: rotate key on first boot
This is a real grep across real files — not hallucinated results. The event log under the Timeline tab records the exact invocation.
2c

System Introspection

Show system information
What happens Routes to system.info deterministically. Returns a 2×2 card grid: OS, CPU count, Python version, hostname. No LLM involved — sub-second response.
"The heuristic router catches obvious tool intents before even waking the LLM. That's why it's fast."
Act 3

"Agents and multi-step plans"

~3 min — Goal: show the planner/executor loop — intent → structured plan → step-by-step execution with a real output.

3a

A Multi-Step Request

Analyze this repository
What happens MachinaOS generates a deterministic 4-step plan — no LLM round-trip, the intent is recognised heuristically:
1. filesystem.tree           → map structure
2. filesystem.read_file      → read README.md
3. git.status                → version control state
4. git.log                   → recent 5 commits
Each step appears as a card in the task timeline with status badges (PENDING → RUNNING → SUCCEEDED). Results accumulate — the final summary references findings from all prior steps via output bridging.
Pause on the plan cards. Each shows: tool name, arguments, risk level, step index. "This is a structured execution plan, not a prompt. Every step maps to a real registered tool. If a step fails, the executor retries or skips gracefully — and the rest of the plan still runs."
3b

Open the Timeline

Click Timeline in the nav (Ctrl+5). The vertical timeline shows every event from the last task: plan_created → tool_started → tool_finished → task_completed. Each event has: timestamp, source component, severity, payload preview.

"Full audit trail, always. Every action is logged whether it succeeded or failed. This is what 'inspectable AI' means."
3c

The Security Scan (sharpest "wow" moment)

Search for hardcoded secrets or API keys in the source code
What happens Routes to a 3-step plan — no LLM needed, pure regex:
  1. filesystem.grep — scan for API key and token assignments
  2. filesystem.grep — scan for passwords, secrets and credential strings
  3. filesystem.grep — scan for private keys and known secret prefixes (sk-live, ghp_, …)
Outcome A — findings detected (Acme seed repo)
Step 1:   0 matches in 156 files
Step 2:  13 matches in 156 files  ← highlighted
Step 3:   0 matches in 156 files
Clicking Step 2 expands:
handler.py:11  SECRET_KEY = "change-me-in-production"
"We saw that string in Act 1. Now the system found it autonomously, in context, without us remembering the file path."

"Step 1 and Step 3 are clean. Step 2 caught the hardcoded secret. Three targeted regex passes, zero false positives on the clean files."
Outcome B — clean codebase (no findings)

All three steps return 0 matches. The plan still completes as 3/3 steps — done. "Green across the board — no hardcoded secrets detected. The scan ran three independent passes. You can wire this into a CI pipeline and treat it as a pass/fail gate."

Both outcomes are equally valid demo moments. Outcome A is more dramatic; Outcome B reinforces that the tool is reliable even when the answer is "nothing found".

Act 4

"Visual Studio" Optional +2 min

Goal: show the Workflow Studio — the visual node-based composer. Studio is fully available in demo mode because read-only chain templates only use safe tools (grep, tree, git.status). No write tools are involved.

4a

Open Studio

Click Studio in the nav (Ctrl+6). The three-panel layout appears: left palette (Tools / Agents / Templates / Chains tabs), centre canvas (grid background, empty), right properties panel (appears when a node is selected).

4b

Browse the Palette

Click the Templates tab. A scrollable list of built-in chain templates appears. Hover over project-scan — a tooltip shows the description and step count.

"Every template is a reusable multi-step workflow. Drag one onto the canvas, wire it to other nodes, and execute it — or build your own from scratch."
4c

Load Chain Templates

Click code-reviewLoad. The canvas auto-fits to show the nodes:

filesystem.tree → git.status → filesystem.grep → filesystem.read_file

Nodes are connected with animated edges, each showing its tool name and a colour-coded risk badge.

Now load project-scan via Open Chain → pick it from the list. The canvas instantly shows the parallel structure:

  • Three scan nodes (filesystem.search, git.status, system.info) sit side-by-side inside a teal dashed bounding box labelled ∥ parallel: scan
  • A single entry node fans out to all three; a single finaliser collects their outputs
"The teal box is the Studio's way of saying: everything inside runs concurrently via asyncio.gather. You can see the concurrency contract without reading any code."

Now load security-audit. Notice a second visual pattern on the canvas:

  • One node carries an amber border ring and an IF corner badge
  • An amber dashed bounding box wraps that node and its two branch targets, labelled ⬦ if: scan_result:matches not_empty
  • The two branch targets are positioned in a diamond fork — one above, one below — connected by a green TRUE edge and an amber FALSE edge
"Amber means conditional. The diamond layout shows the fork visually. The edge colour tells you which branch ran: green = condition met, amber = condition not met. No YAML. No DSL. Just canvas geometry."
4d

Execute with Live Visuals

Click ▶ Execute in the Studio toolbar and watch the canvas:

  • filesystem.tree pulses amber (running), then turns green ✓
  • git.status starts pulsing — and so on through all 4 nodes

Once all nodes are green, a summary banner appears at the top of the results tray:

✓  Done — 4/4 steps completed successfully.
   ✓ filesystem.tree
   ✓ git.status
   ✓ filesystem.grep
   ✓ filesystem.read_file

The banner is green on full success, red on partial failure. Each step output below it uses the same smart formatters as the chat view — tree icons, grep grouping by file, git branch badges.

"This is the same execution engine as the chat. The visual Studio is just a different way to compose and run the same plans — with a canvas instead of a text prompt."
4e

Extend the Chain with Your Own Node

The template scans for TODO/FIXME markers. Add a second grep that looks for hardcoded passwords — same idea, different pattern — without touching the other nodes.

  1. In the Tools tab of the palette, type grep in the filter box. Drag filesystem.grep onto an empty area of the canvas.
  2. Click the new node. In the Properties panel fill in:
    • Querypassword|secret|passwd
    • Path ← leave blank (filled from active workspace)
    • Output Keypw_scan
  3. Hover over the output port of the previous filesystem.grep node — drag to the input port of your new node. The Bezier curve snaps into place.
  4. Click ▶ Execute again. Your node runs 5th — if the Acme repo is loaded it finds SECRET_KEY = "change-me-in-production" in handler.py.
"One drag, one property, one edge. The chain grew from 4 steps to 5. You didn't write any code or config — you just composed tools on a canvas."
4f

Step Through with the Debugger Optional

Click the arrow next to Execute and choose Debug (or click the bug icon in the toolbar). The Studio switches to debug mode:

  • A debug toolbar appears: Step Over / Continue / Stop buttons with a step counter (0 / 5)
  • All nodes dim to their "pending" state

Click Step Over once: filesystem.tree pulses amber, then turns green ✓. Counter advances to 1 / 5.

Click Step Over again: git.status runs and succeeds. Counter: 2 / 5. Branch name appears in the results tray.

Click Continue to run the remaining steps at full speed. All nodes turn green.

"The debugger uses the same execution engine — it just pauses between steps so you can inspect intermediate outputs before the next tool fires. Useful when you're building a chain and want to verify each stage."

If time is short: do one Step Over to show the pause, then hit Continue to finish.

4g

Build a Conditional Chain from Scratch Optional · ~90 s

Clear the canvas (New Canvas in the Studio toolbar), then build a branching chain live.

  1. Evidence gather. Drag filesystem.grep from the palette onto the canvas. In Properties: QueryTODO|FIXME · Output Keytodos
  2. Conditional gate. Drag git.status to the right of the grep node. In Properties: Output Keygit_state · Conditiontodos:matches not_empty.
    The node immediately renders with an amber border ring and an IF corner badge — it is now a decision point, not just a step.
  3. Wire both branches.
    • Draw a TRUE edge (green output port) from the IF node → a new git.log node. "If TODOs exist, review the commit history."
    • Draw a FALSE edge (amber output port) from the IF node → a new filesystem.tree node. "If the codebase is clean, just show the structure."
    An amber dashed bounding box appears automatically around the IF node and both branch targets, labelled ⬦ if: todos:matches not_empty. The two targets sit above and below the IF node — a diamond fork.
  4. Execute. Click ▶ Execute.
    • If TODOs are found: git.log branch lights green; filesystem.tree dims to 18% opacity (not taken)
    • If the codebase is clean: filesystem.tree executes; git.log stays dim
"Green edge — condition met, path taken. Amber edge — not met, path skipped. The graph makes the contract visible. No code change required to read it."
Act 5

"Agents" Optional +2 min

Goal: show the Agents view for visitors curious about multi-agent coordination. Best for technical audiences.

5a

Open the Agents View

Click Agents in the nav. The Fleet sub-tab shows the 4 built-in agents: filesystem, git, shell, system — each with capability badges and health status (ONLINE).

5b

Agent Awareness in Chat

ask agent git to show the project history
What happens The intake parser detects the delegation pattern ("ask agent git"). A plan step is generated with delegate_to: git pointing to git.log. The git agent's tool filter confirms it owns git.* tools. Result: a formatted commit log.
"You can talk to specific agents by name. Each agent has a scoped tool filter — the git agent can only touch git tools. The system enforces that at execution time."
5c

The Communication Graph

Click the Communications sub-tab inside the Agents view.

The left panel shows a real-time SVG graph of every inter-agent message exchanged during your session:

  • Each node is an agent circle with its name and a small traffic pill showing messages sent/received
  • Edges are directed arrows, colour-coded by message type:
    • Cyan — direct agent requests
    • Amber — negotiation proposals
    • Purple — task handoffs
    • Emerald — broadcast queries
  • Multiple messages between the same pair are aggregated into a single edge with an ×N count pill

Click ⤢ Expand in the graph header for a fullscreen overlay — 96 vw × 90 vh, with scroll-to-zoom and drag-to-pan.

"This is a live map of how the agent fleet is coordinating. Every arrow represents a real message passed over the agent bus — not a diagram someone drew by hand."

Tip: run a couple of delegation prompts in 5b before showing this panel — the graph is more impressive with multiple edges already populated.

Act 6

"Describe It, Build It" — NL Chain Generation Optional +2 min

~2 min — Goal: show that you never have to build a workflow chain step by step. Describe what you want in plain English — MachinaOS generates a fully structured, executable chain in seconds.

6a

Generate a Chain from Chat

Stay in the Neural Link (Chat tab). Type one of the following generation phrases — the heuristic parser recognises them instantly and routes to the NL Chain Generator, bypassing the normal planning loop entirely.

Create a chain that checks for secrets and credentials in my codebase
What happens
  1. The parser detects create a chain → intent generate_chain
  2. The active LLM's native tool-use API is called with the prompt and the full tool catalog — Claude uses function-calling; GPT-4o uses the same; Gemini uses function declarations; Ollama falls back to JSON-mode prompting
  3. The LLM fills a strict step schema — tool by tool, argument by argument — with zero free-form text to parse
  4. Unknown tools are filtered, steps are capped at 12, empty argument maps are filled in
  5. The chain is persisted to chains.db and a result card appears with Open in Studio and View Chains buttons
"You described it. Machina OS built it. One sentence — a fully wired, versioned, executable workflow chain ready to run or edit."

More generation phrases to try (all work identically):

Build a morning briefing chain: check system health, git status, and recent logs
Generate a chain to onboard a new project: scan structure, read README, list deps, check Docker
Create a release preparation chain: status check, changelog review, and tag push
6b

Generate from Studio — the ✨ Generate Button

Open Studio (Ctrl+6). In the toolbar you'll see the ✨ Generate button alongside Execute, Debug, Auto-Assign, and Optimize.

  1. Click ✨ Generate — a small modal appears with two fields: Chain name and Description
  2. Enter a name (e.g. Daily Standup) and type the description:
    "List recent commits, open tasks, disk usage, and system load"
  3. Submit — the chain populates on the canvas immediately with full layout logic applied
What the canvas shows
  • Steps that can run concurrently appear inside a teal dashed swim-lane box (∥ parallel)
  • Conditional steps carry an amber border ring and an IF corner badge
  • Agents are auto-placed where the system infers them from tool patterns (e.g. git.* tools → git agent)
"Describe it. Build it. The canvas speaks the same visual grammar as a hand-crafted chain — because it is one. Auto-assign agents, hit Execute, or step through with the debugger. The generated chain is version 1 — edit it like any other."
6c

Generate via API Optional — for technical audiences

The same engine is exposed as a REST endpoint. Run this from a terminal while the demo is open:

curl -X POST http://127.0.0.1:8100/workflow-chains/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Generate a workflow that runs daily: list processes, check disk, and save a status note",
       "name": "Daily Ops Auto"}'
What the response includes

A full chain record: id, name, version: 1, steps array with tools, agents, output keys, and arguments — ready to execute or wire into CI/CD. Switch to Studio, click Open, and the generated chain loads onto the canvas in one click.

"Any system that can make an HTTP call can generate a chain on demand — no human in the loop, no UI required. Describe it, build it, run it."
Act 7

"Webhook Triggers — Run Chains from Anywhere" Optional +2 min

~2 min — Goal: show that any chain can be triggered by an external system via a stable HTTP endpoint — a CI/CD pipeline, a monitoring alert, a GitHub Action — no user interaction required.

7a

Open the Webhooks Panel

Click Agents in the nav → Pipelines sub-tab → Webhooks. The create form has three fields:

  • Chain — select any saved chain from the dropdown
  • Description — a human-readable label (e.g. "Post-build security scan")
  • Secret — optional HMAC-SHA256 signing secret for authenticated callers

Click Create Webhook. A card appears instantly showing:

  • The trigger URL with a one-click copy button — this URL is stable and never changes when the chain is updated
  • An enable / disable toggle
  • An invocation count pill
  • An expandable Invocation History section (last 20 runs — timestamp, status, duration)
7b

Trigger the Webhook

Copy the trigger URL from the card, then fire it from a terminal:

curl -X POST http://127.0.0.1:8100/webhooks/{chain_id} \
  -H "Content-Type: application/json" \
  -d '{}'
What happens
  1. The server validates the request (signature check if a secret was set) and returns {"status": "running"} immediately
  2. The chain executes in the background — exactly as if you had clicked Execute in the UI
  3. The run appears in the Chain Execution History panel alongside manual runs
  4. The webhook card's invocation counter increments and the new run appears in Invocation History
"Your CI/CD pipeline just triggered a security audit. No polling, no agent running 24/7, no Machina UI open. One POST — the chain runs, the results are stored, the audit trail is complete."
7c

Security — HMAC-SHA256 Signatures Optional — for security-conscious audiences

When you create a webhook with a secret, Machina OS stores a one-way hash — the plaintext is never saved. A caller authenticates by computing an HMAC-SHA256 digest of the request body and including it in the X-Machina-Signature header:

BODY='{"overrides":{}}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your-secret" | awk '{print $2}')

curl -X POST http://127.0.0.1:8100/webhooks/{chain_id} \
  -H "Content-Type: application/json" \
  -H "X-Machina-Signature: $SIG" \
  -d "$BODY"
Security model
  • The server recomputes the digest and compares using a constant-time comparison — no timing attacks
  • Mismatched signatures → 403 Forbidden — chain does not execute
  • Webhooks without a secret are open — fine for internal networks, use secrets for internet-exposed endpoints
"Chain executions from external systems are first-class — authenticated, logged, and visible in the same audit trail as manual runs. Nothing happens in the shadows."

What You Can't Do — and Why

The online demo runs in DEMO mode — a deliberate read-only sandbox. If you try a blocked action, MachinaOS returns a clear DEMO_TOOL_BLOCKED error — not a silent failure.

Blocked action Reason
filesystem.write_file Shared workspace — writes would leak between sessions
shell.run Arbitrary command execution on a remote server
process.stop Would kill other visitors' sessions
git.push, git.commit No write access to the repo
LLM settings changes Shared GPT-4o-mini config for all sessions

Suggested Prompts to Explore on Your Own

All of these work in the live sandbox — pick any and run them in the Neural Link.

Prompt What it demonstrates
Show disk usage system.disk — real server metrics
List running processes process.list — live process table
Read the users API filesystem.read_file — syntax-highlighted source
Search for email addresses in the code filesystem.grep + regex pattern matching
What is the git status? git.status — branch, staged/unstaged files
Show recent commits git.log — formatted commit history
What can Machina OS do? Conversational LLM answer with tool catalog
Show memory usage system.memory — available/used GB cards
Create a chain that checks for secrets and credentials in my codebase NL Chain Generation — "Describe It, Build It" — auto-builds a multi-step secret-scan chain
Build a morning briefing chain: check system health, git status, and recent logs NL Chain Generation — 3-step startup chain generated from plain English
Generate a workflow that runs daily: list processes, check disk, and save a status note NL Chain Generation via Neural Link — chain persisted to chains.db, opens in Studio

If Asked "Is This Production-Ready?"

"What you're seeing is Sprint 86 — 2273 passing tests, a full runtime contract layer with state-machine-guarded task and step transitions, an AES-256-GCM secrets vault, a SOC 2-compatible audit log, a Tauri 2 desktop shell that ships as a zero-prerequisite MSI, a visual Studio with conditional diamonds, parallel swim lanes, and live debugger stepping, NL Chain Generation that turns a single sentence into an executable pipeline, and a Webhook engine so any external system can trigger your chains via HMAC-signed HTTP POST. The hosted demo intentionally runs in a read-only sandbox so you can explore safely. The full system runs locally — no data leaves your machine."

Presenter Checklist

For live walk-throughs — run through this before starting.

Before You Start

  • LLM status dot is green in the bottom bar
  • Orientation overlay dismissed
  • Start with the quick-prompt "Explore the project" to warm up

The Core Narrative

  • Run Acts 1 → 2 → 3 in order (each builds on the prior output)
  • Pause on the plan cards — let the audience read the step list
  • Open the Timeline after Act 3 to show the audit trail
  • Security scan last in Act 3 — it's the sharpest "wow" moment

Optional Acts

  • Act 4 (Studio): load code-review template, execute, show live node animation and summary banner
  • Act 4e: drag filesystem.grep onto canvas, set Query to password|secret|passwd, draw edge, execute
  • Act 4f: Debug mode — Step Over once (amber → green), Continue for the rest
  • Act 5 (Agents): for technical audiences asking about agent coordination
    • 5a: Fleet sub-tab — 4 built-in agents with health status
    • 5b: ask agent git to show the project history — delegation to git agent
    • 5c: Communications sub-tab — live SVG agent graph, click ⤢ Expand for fullscreen
  • Act 6 (NL Chain Generation — "Describe It, Build It"): highest-impact optional act for product-focused audiences
    • 6a: type Create a chain that checks for secrets and credentials in my codebase in Neural Link — chain generates in seconds, result card shows Open in Studio and View Chains
    • 6b: open Studio → click ✨ Generate — enter name + description, canvas populates with teal parallel lanes and amber conditional nodes fully wired
    • 6c (technical): show the POST /workflow-chains/generate curl call for API-first integrations
    • Key line: "One sentence. A fully wired, versioned, executable chain. Describe it, build it."
  • Act 7 (Webhooks): for DevOps and CI/CD audiences
    • 7a: Agents → Pipelines → Webhooks — create webhook, copy stable trigger URL
    • 7b: fire curl -X POST .../webhooks/{chain_id} from terminal — chain runs, appears in execution history
    • 7c (security-focused): show HMAC-SHA256 signature example
    • Key line: "One POST — chain runs, results stored, audit trail complete. No user required."

Wrap-Up

  • Leave 2 minutes for free exploration / audience-driven prompts
  • Point to the Demo Guide for reviewer and press tokens
  • Offer to reset the workspace if they want a clean slate

Ready to explore

Open the live demo in a new tab and follow the storyboard — or just start typing.

Launch Demo → Demo Ground Rules Browse Screens