Product Demo Runbook

This runbook is the definitive guide for demonstrating the capabilities of the IBM i AI Platform. It covers the three primary surfaces: the Web Application, the Desktop Application, and the standalone MCP Server.

---

1. Application Overview

1.1 Web Application

The Web Application provides a full-featured, authenticated, multi-user experience. It is designed for enterprise environments where governance and auditability are paramount.

• Key Features: DB-backed approval workflows, multi-role access control (e.g., Security Officer vs. Operator), conversation history, and rich visual analytics.
• Best For: Demonstrating governed administration, team-based operations, and long-running audit trails.

1.2 Desktop Application

The Desktop Application is a localized, high-performance surface focused on observability and deep system diagnostics.

• Key Features: Native chart rendering, direct system integration, and support for various AI providers (Anthropic, OpenAI, Gemini, xAI, GitHub Copilot, Local).
• Best For: Individual operators, rapid troubleshooting, and interactive visual data analysis.

1.3 Standalone MCP Server

The standalone Model Context Protocol (MCP) server allows you to bring IBM i capabilities into any AI-powered tool that supports the MCP standard.

• Key Features: Standardized tool definitions, lightweight execution, and broad compatibility.
• Best For: Developers and power users who want to use IBM i tools within Codex, VS Code, Cursor, Claude Desktop, or Antigravity CLI.
• Usage: Run directly via npx @bdkinc/ibmi-mcp.

---

2. Getting Started: IBM i Connection Guide

Before running a demo, ensure your environment can connect to the target IBM i partition.

2.1 Prerequisites

• IBM i Access ODBC Driver: Required for database-backed tools and metadata retrieval.
• Network Access: The client machine must have connectivity to the IBM i host (Ports: 449, 8470-8476, 9470-9476 for ODBC/SQL; Port 22 for SSH).
• User Profile: A valid IBM i user profile with appropriate authorities for the tools you intend to demonstrate (e.g., *JOBCTL for job management, *SECADM for user management).

2.2 SSH Connection & Caveats

Many advanced tools (like job log retrieval or IFS operations) rely on SSH for execution.

• SSH Daemon: Must be active on the IBM i (STRTCPSVR SERVER(*SSH)).
• Environment Variables: Some tools may require PASE environment variables to be correctly set in the user profile.
• Key-Based Auth: While password authentication is supported, key-based authentication is recommended for the most seamless experience.
• Caveat: Ensure the SSH terminal on IBM i is configured to handle the expected character encoding (usually UTF-8) to avoid data corruption in logs or IFS files.

---

3. Tool Integrations (MCP Server)

The standalone MCP server (npx @bdkinc/ibmi-mcp) can be added to any compliant client.

3.1 Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "ibmi": {
      "command": "npx",
      "args": ["-y", "@bdkinc/ibmi-mcp"],
      "env": {
        "IBMI_HOST": "your-system-name",
        "IBMI_USER": "your-user",
        "IBMI_PASSWORD": "your-password"
      }
    }
  }
}

3.2 VS Code

Install the MCP Client extension (or similar) and add a new server configuration using the same npx command and environment variables as above.

3.3 Cursor / AI Code Editors

In Cursor, go to Settings > Features > MCP and add a new server:

• Type: command
• Command: npx -y @bdkinc/ibmi-mcp
• Ensure your environment variables (Host, User, Password) are set in your system shell or the editor's environment settings.

3.4 Codex

Codex can run the standalone IBM i MCP server as a local MCP tool source. Add an ibmi server entry to your Codex MCP configuration:

[mcp_servers.ibmi]
command = "npx"
args = ["-y", "@bdkinc/ibmi-mcp"]

[mcp_servers.ibmi.env]
IBMI_HOST = "your-system-name"
IBMI_USER = "your-user"
IBMI_PASSWORD = "your-password"

Restart Codex after saving the configuration, then ask Codex to list available MCP tools or run a read-only IBM i observation such as Check QSYSOPR and tell me whether any messages still require attention.

3.5 Antigravity CLI

If you are using Antigravity CLI, you can activate the IBM i capabilities by adding the server to your agent configuration.

---

4. Desktop App Configuration (AI Providers)

The Desktop Application allows you to choose your preferred AI provider for reasoning and tool orchestration.

4.1 Supported Providers

• Anthropic: Best-in-class reasoning and tool use (requires an API Key).
• OpenAI: Industry standard for speed and capability (requires an API Key).
• Google Gemini: Strong multimodal and long-context reasoning (requires an API Key).
• xAI: Grok models for teams that want xAI-hosted reasoning (requires an API Key).
• GitHub Copilot: Leverage your existing GitHub Copilot subscription.
• Local Models: Connect to local instances via Ollama or LM Studio (ideal for high-security environments).

4.2 Configuration

1. Open the Settings panel in the Desktop App.
2. Select the AI Provider tab.
3. Choose your provider and enter the required API Key or Base URL (for local models).
4. Save the settings and the app will automatically reconnect to the AI service.

---

5. Guided Demo Flows

5.1 The "Best Short Demo" (10 Minutes)

Use this sequence for a high-impact overview of the platform.

1. Platform Readiness: Run a system health check and summarize the biggest risks. (Invokes inspect_system view: "health")
2. Visual Analytics (Desktop): Create a pie chart showing the top libraries and their storage usage. (Invokes inspect_storage view: "consumers" and render_chart)
3. Operational Triage: Check whether QSYSOPR has any unanswered messages right now. (Invokes inspect_messages view: "qsysopr")
4. Governed Change: Plan resetting DEMOUSR's password to DemoPwd123 and require a password change at next sign-on. Show the preview approval workflow. (Invokes manage_user_profile operation: "reset_password", mode: "preview")
   • Presenter note: on partitions where QPWDMAXLEN is 8, this intentionally demonstrates live IBM i password-policy validation. Explain the rejection, then retry with Demo1234 to show the successful path.

5.2 Desktop Application Narrative

Focus: Observability, diagnostics, and rich visual feedback.

• Part 1: Broad Observability

  Run a system health check and summarize the biggest risks. (Invokes inspect_system view: "health")

• Part 2: Visual Grounded Analytics

  Create a pie chart showing the top libraries and their storage usage. (Invokes inspect_storage view: "consumers" and render_chart)

• Part 3: Focused Drill-Down

  Find active jobs that are currently waiting, then inspect the job log for job 123456/QUSER/QPADEV0001 and summarize the last 20 messages. (Invokes inspect_jobs view: "active" followed by inspect_messages view: "job_log")

• Part 4: Safe Admin Workflows

  Plan resetting DEMOUSR's password to DemoPwd123 and require a password change at next sign-on. (Invokes manage_user_profile operation: "reset_password", mode: "preview") If the target policy rejects the password length, call out that this is the platform enforcing IBM i system values, then retry with Demo1234.

5.3 Web Application Narrative

Focus: Multi-user collaboration, compliance, and zero-trust governance.

• Part 1: Multi-User Observability

  Run a system health check and summarize the biggest risks. (Invokes inspect_system view: "health")

• Part 2: Compliance Review

  Check system audit journal readiness. Tell me whether auditing is enabled. (Invokes inspect_security view: "audit_configuration")

• Part 3: Advanced Guardrails

  Plan stopping the FTP server. (Invokes manage_tcp_server operation: "end", mode: "preview")

• Part 4: Approval Lifecycle

  Plan a privileged IBM i command execution for CHKOBJ OBJ(QSYS/QGPL) OBJTYPE(*LIB) to generate an approval request. (Invokes plan_run_ibmi_command) (Note: Demonstrate how another user with the 'Security Officer' role would approve this request in the Web UI, generating an approvalTicket to execute with run_ibmi_command).

---

6. Comprehensive Prompt Bank

Use these prompts to explore the full depth of the platform's capabilities.

6.1 Health and Observability

• Run a system health check and summarize the biggest risks. (Invokes inspect_system view: "health")
• Check storage usage summary and tell me whether capacity looks healthy. (Invokes inspect_storage view: "summary")
• Create a pie chart showing the top libraries and their storage usage. (Invokes inspect_storage view: "consumers" and render_chart)
• Check active jobs and show the top CPU jobs with subsystem names. (Invokes inspect_jobs view: "active")
• Check QSYSOPR and tell me whether any messages still require attention. (Invokes inspect_messages view: "qsysopr")
• Check recent system history log messages and call out high-severity items. (Invokes inspect_messages view: "history_log")
• Check memory pools and summarize the largest pools. (Invokes inspect_system view: "memory_pools")

6.2 Diagnostics and Drill-Down

• Get the job log for job 123456/QUSER/QPADEV0001 and summarize the last 20 messages. (Invokes inspect_messages view: "job_log")
• Read the spooled file content for job 123456/QUSER/QPADEV0001 spool QPRINT. (Invokes inspect_spool view: "spooled_file_content")
• Check active TCP listeners and tell me what is listening on common application ports. (Invokes inspect_network view: "tcp_listeners")
• List objects in library QGPL and summarize the object types you find. (Invokes inspect_objects view: "library_objects")
• List the IFS directory contents for /home/app and summarize what is present. (Invokes inspect_ifs view: "directory")
• Check the security system values. (Invokes inspect_system view: "system_values")

6.3 Safe Preview Workflows (Recommend)

• Plan creation of user DEMOUSR with text "Demo operations user" and limited capabilities. (Invokes manage_user_profile operation: "create", mode: "preview")
• Plan resetting DEMOUSR's password to DemoPwd123 and require a password change at next sign-on. (Invokes manage_user_profile operation: "reset_password", mode: "preview"; if rejected by QPWDMAXLEN, explain the policy check and retry with Demo1234.)
• Plan ending the FTP server and explain the risk. (Invokes manage_tcp_server operation: "end", mode: "preview")
• Plan changing the owner of object QGPL/QPRINT of type *OUTQ to QSECOFR. (Invokes manage_object_security operation: "change_owner", mode: "preview")
• Plan granting *USE authority on object QGPL/QPRINT to user IBMIAI. (Invokes manage_object_security operation: "grant_authority", mode: "preview")

6.4 Admin Action Workflows (Act - After Approval)

• Execute creation of user DEMOUSR (using previewId, previewToken, and approvalTicket). (Invokes manage_user_profile operation: "create", mode: "execute")
• Execute password reset for user DEMOUSR (using previewId, previewToken, and approvalTicket). (Invokes manage_user_profile operation: "reset_password", mode: "execute")
• Execute ending job 123456/QUSER/QPADEV0001 (using previewId, previewToken, and approvalTicket). (Invokes manage_job operation: "end", mode: "execute")
• Execute starting TCP server FTP (using previewId, previewToken, and approvalTicket). (Invokes manage_tcp_server operation: "start", mode: "execute")
• Execute starting subsystem QINTER (using previewId, previewToken, and approvalTicket). (Invokes manage_subsystem operation: "start", mode: "execute")

6.5 Security Approval Flows

• Plan a privileged command execution for CHKOBJ OBJ(QSYS/QGPL) OBJTYPE(*LIB) to generate an approval request. (Invokes plan_run_ibmi_command)
• Execute approved command for ticket 101. (Invokes run_ibmi_command with approvalTicket)

---

7. Learning Notes & Teach Moments for Self-Study

7.1 Navigate the Learning Hub

Use these resources to go from demo spectator to confident operator.

7.2 The Observe-Recommend-Act Workflow

Every capability in this platform follows the same safety loop. Use this diagram to recognize where you are before you press Enter.

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   OBSERVE   │ --> │  RECOMMEND   │ --> │    ACT      │
│  (Read-only)│     │  (Plan/Safe) │     │ (Governed)  │
└─────────────┘     └──────────────┘     └─────────────┘
       │                    │                   │
       ▼                    ▼                   ▼
  Gather system      Explain risk and      Execute only
  facts, logs,       preview before        with approval,
  and metrics        making changes        audit trail,
                     with safe previews    and approval ticket

Safety rule: If you cannot articulate what you observed, do not proceed to Act. The AI always offers a Plan/Preview step before executing any changes.

7.3 Teach Moments

Teach moments are conceptual anchors tied to specific demo prompts. Use them to turn a scripted demo into an active coaching session.

Moment 1: Why the Health Check Comes First

Demo prompt: Run a system health check and summarize the biggest risks.

Moment 2: The Approval Lifecycle Value

Demo prompt: Plan a privileged command execution for CHKOBJ OBJ(QSYS/QGPL) OBJTYPE(*LIB) to generate an approval request.

Moment 3: Visual Grounding Before Narrative

Demo prompt: Create a pie chart showing the top libraries and their storage usage.

Moment 4: Safe Preview Workflows

Demo prompt: Plan resetting DEMOUSR's password to DemoPwd123 and require a password change at next sign-on.

7.4 Turn This Demo into Self-Study

Use the checkpoints below to run through this runbook solo. Do not advance until you can answer the question out loud.

Solo study protocol

1. Run the prompt.
2. Read the AI response slowly—look up any glossary term you do not recognize.
3. Ask, "What could go wrong?" before every Act step.
4. Document your answers in a personal notebook or the Self-Study Runbook.
5. Repeat the checkpoint the next day without looking at your previous answers.

---

Last updated: 2026-05-21