ixora

CLI for managing ixora AI agent deployments on IBM i — and for talking to the running AgentOS.

[!TIP] Full documentation lives in docs/ — every command, every flag, with examples. Start with Getting Started or browse the docs index.

Install

npm install -g @ibm/ixora

Or run directly with npx:

npx @ibm/ixora stack install

Requirements

• Node.js >= 22
• Docker Desktop (or Podman)
• An IBM i system with Db2 for i
• An API key for your chosen model provider (Anthropic, OpenAI, Google, or Ollama for local)

Quick Start

ixora stack install    # Interactive setup (IBM i connection, model provider, profile)
ixora stack start      # Start services (defaults to --profile full = DB + API + MCP + UI)
ixora stack stop       # Stop services

Once an instance is up, talk to AgentOS directly:

ixora agents list      # List registered agents
ixora agents run <id> "what's running on QSYS?"
ixora chat             # Interactive chat TUI (agents, teams, workflows)
ixora traces list      # See recent runs
ixora sessions list    # Browse sessions
ixora knowledge bases  # List knowledge bases (e.g. "User Documents")
ixora knowledge search "..."

Attach a knowledge base to an agent by its display name when you create or update it:

ixora agents create --name "Docs Helper" --id docs-helper \
  --model anthropic:claude-sonnet-4-6 --knowledge "User Documents"

If only one instance is available, those commands target it implicitly. With 2+ instances available you have two options:

ixora --instance prod agents list           # one-off override
ixora instances default prod                # set a persistent default
ixora agents list                         # now uses 'prod' implicitly
ixora --instance dev agents list            # flag still wins over the default
ixora instances default --clear             # back to "must specify --instance"

The AgentOS directory (ixora instances)

ixora instances is the one place to see and target every AgentOS, regardless of how it was created — stack local stacks, external URLs, and workspace codebases:

ixora instances                             # directory: ID + URL + KIND + running indicator
ixora instances list --json                 # scriptable (flat array)
ixora instances default prod                # set/clear the default target
ixora instances remove <id>                 # remove any instance from the directory

External AgentOS endpoints

Beyond the IBM i stacks ixora provisions ("stack" instances), you can register any AgentOS-compatible URL as a target — typically another locally-running AgentOS instance you spun up from a different template, but the URL can be remote too. ixora doesn't lifecycle-manage these ("external" instances); it just routes runtime commands at them.

ixora instances add                                          # interactive
ixora instances add --id personal \
  --agentos-url http://localhost:8080 [--agentos-key sk-xxx] # non-interactive

ixora instances                                              # directory: KIND + URL + running indicator
ixora --instance personal agents list                        # target the external by name

Externals always count as "available" (no docker container check), so the implicit-pick rule extends naturally: 1 available → pick it; 2+ → require --instance (or IXORA_DEFAULT_INSTANCE). The optional --agentos-key is stored as SYSTEM_<ID>_AGENTOS_KEY in ~/.ixora/.env.

Two command surfaces

The ixora binary exposes two trees:

| Tree | Purpose | Examples | |---|---|---| | ixora stack ... | Manage the local stack: install, start/stop, configure, add IBM i systems | ixora stack install, ixora stack add, ixora stack config set ... | | ixora <runtime> ... | Talk to the running AgentOS (ported from the standalone agno-cli) | ixora agents, ixora teams, ixora workflows, ixora traces, ixora sessions, ixora knowledge, ixora memories, ixora evals, ixora approvals, ixora schedules, ixora metrics, ixora databases, ixora registries, ixora components, ixora models, ixora status |

ixora <runtime> commands always pick a target instance (the only running one by default; --instance <name> to choose). ixora stack commands are unaffected by --instance — they have their own targeting (ixora stack start <id>, etc.). The third surface, ixora instances, is the cross-kind directory: it lists and targets every AgentOS (stack, external, workspace) and registers external URLs. A fourth, ixora workspace, scaffolds and runs standalone AgentOS workspaces from starter templates via Docker — it talks to Docker directly and never consumes --instance/--url.

Deployment shapes (--profile)

| Profile | Containers | Use case | |---|---|---| | full (default) | DB + API + MCP + Carbon UI | Local development, the bundled web UI | | mcp | DB + API + MCP | Backend-only — bring your own UI, or run as a service |

ixora stack start --profile full  # All four services (default)
ixora stack start --profile mcp   # No Carbon UI; API on :18000, DB on :15432

The chosen profile is persisted to ~/.ixora/.env, so subsequent stop/status/logs/restart/upgrade calls without --profile keep the same shape. Switching mid-session is safe: ixora stack stop --profile mcp while in full leaves the UI container untouched.

The old --profile api is accepted as an alias for --profile mcp (with a one-line warning). The removed --profile cli is likewise coerced to mcp — agents now always reach IBM i through the MCP server. See IXORA_QUICKSTART.md → §8 "Stack profiles".

Per-system database isolation

By default each IBM i system gets its own ai_<id> Postgres database (and its own /data volume) inside the shared agentos-db container — so sessions, memory, knowledge, and learnings are isolated per system. A single-instance deployment is just agentos-db with an ai_default database (nothing extra); with 2+ instances a one-shot db-init service provisions the additional databases. To put everything back in one shared ai database instead: ixora stack config set IXORA_DB_ISOLATION shared && ixora stack restart. See IXORA_QUICKSTART.md → §4 "Advanced: per-system database isolation".

Stack commands

| Command | Description | |---------|-------------| | stack install | First-time setup (interactive) | | stack start | Start services | | stack stop | Stop services | | stack restart [service] | Restart all or a specific service | | stack status | Show service status and deployed profile | | stack upgrade | Pull latest images and restart | | stack uninstall | Stop services and remove images | | stack logs [service] | Tail service logs | | stack version | Show CLI and image versions | | stack config show | Show current configuration | | stack config set <key> <value> | Update a config value | | stack config edit | Open config in your editor | | stack add | Provision a new stack-kind (local) IBM i instance. Flags: --id ... --name .... (External URLs → ixora instances add.) | | stack remove <id> | Remove a stack instance (cleans up env keys; also available as ixora instances remove) | | stack list | List stack instances with URL + PACKS columns (see ixora instances for all kinds) | | stack start\|stop\|restart <id> | Manage one stack instance's containers (errors with a hint if <id> is external) | | stack packs list [instance] | List packs the deployed image declares and which are enabled on an instance | | stack models show\|set | View / switch model provider | | stack packs select [instance] | Choose which packs are enabled on an instance (pack picker) | | stack connection show [instance] | Show an instance's IBM i JDBC options (read-only access by default) | | stack connection set\|unset <instance> <key> [value] | Set / remove a JDBC option (library list, naming, access, …) |

AgentOS directory (ixora instances)

The cross-kind registry of every AgentOS you can target — stack, external, and workspace.

| Command | Description | |---------|-------------| | instances list | List every instance (stack/external/workspace) with a live running indicator. --json [fields] for a scriptable array. Default subcommand — ixora instances alone runs it. | | instances add | Register an external AgentOS URL. Flags: --id ... --name ... --agentos-url ... --agentos-key ... | | instances remove <id> | Remove any instance from the directory (stack/external/workspace; cleans up env keys) | | instances default [id] [--clear] | Show, set, or clear the default target used when 2+ are available and --instance is omitted |

Workspaces (ixora workspace)

Scaffold, run, and tear down standalone AgentOS workspaces (cloned starter templates) with Docker. Workspace commands talk to Docker directly and never consume --instance/--url. See docs/workspace.md for the full reference.

| Command | Description | |---------|-------------| | workspace create | Clone a starter template into a new directory and register it as a workspace instance. Flags: -t ibmi-agentos-docker\|ibmi-agentos-openshift, -u <git-url>, -n <name>, --port <n> (container port for ixora instances URL discovery; default 8000) | | workspace up [filter] | Create the workspace's resources (or run its Compose file) | | workspace down [filter] | Delete the workspace's resources | | workspace patch [filter] | Update existing resources | | workspace restart [filter] | down then up | | workspace config | Print the active workspace's config | | workspace delete [--name <name>] | Remove a workspace record (does not delete files) |

AgentOS runtime commands

| Command | Description | |---------|-------------| | chat [--agent\|--team\|--workflow <id>] | Interactive chat TUI: streamed runs, tool rendering, inline confirmations (TTY only) | | agents list\|get\|run\|continue\|cancel\|create\|apply\|update\|delete | Manage agents (including the agent definition itself) | | teams list\|get\|run\|continue\|cancel | Manage teams | | workflows list\|get\|run\|continue\|cancel | Manage workflows (gated — off by default) | | traces list\|get\|stats\|search | Inspect traces | | sessions list\|get\|create\|update\|delete\|delete-all\|runs | Manage sessions | | memories list\|get\|create\|update\|delete\|delete-all\|topics\|stats\|optimize | Manage memories | | knowledge bases\|upload\|list\|get\|search\|status\|delete\|delete-all\|config | Manage knowledge bases (bases lists them; upload/search/etc. target one) | | evals list\|get\|delete | Manage eval runs (gated — off by default) | | approvals list\|get\|resolve | Manage approvals (gated — off by default) | | schedules list\|get\|create\|update\|delete\|pause\|resume\|runs | Manage schedules (gated — off by default) | | metrics get\|refresh | View / refresh metrics | | databases migrate <db_id> | Run database migrations | | registries list | List registry items | | components list\|get\|create\|update\|delete\|config ... | Manage components in AgentOS | | models list | List available models in AgentOS | | status | Show AgentOS server status and resource overview | | health | Ping /health on the resolved instance; reports status + uptime + latency (exits non-zero when unhealthy) | | docs | Inspect the AgentOS server's raw HTTP API via /openapi.json |

Gated commands (ixora features)

workflows, evals, approvals, schedules, and workspace are off by default — hidden from --help and not runnable. Each is enabled independently:

ixora features list                 # show every gated feature and its state
ixora features enable workflows     # turn one on (persists to ~/.ixora/config.yaml)
ixora features enable evals schedules
ixora features disable workflows

Running a disabled command prints how to enable it and exits non-zero. For CI/one-off use, an environment override skips the config file:

IXORA_FEATURE_WORKFLOWS=1 ixora workflows list   # this invocation only

Precedence: IXORA_FEATURE_<NAME> (env) → ~/.ixora/config.yaml → off.

Global options

# Stack shape & install-time
--profile <name>       Stack shape: full / mcp  [default: full]
--packs <ids>          Packs to enable at install: comma-separated ids, or 'all' (install-time)
--image-version <tag>  Pin image version (e.g., v1.2.0)
--no-pull              Skip pulling images
--purge                Remove volumes too (with uninstall)
--runtime <name>       Force docker or podman

# AgentOS targeting (consumed by ixora <runtime> ... commands)
-i, --instance <name>  Target a specific configured instance. Implicit when only one is
                       running, or when the configured default (ixora instances default)
                       is in the running set. Always wins when supplied.
--url <url>            Override AgentOS endpoint entirely (skips instance resolution)
--key <key>            Override AgentOS API key for this invocation
--timeout <seconds>    Override request timeout in seconds
--no-color             Disable color output
--json [fields]        Emit JSON; `--json id,name` projects fields
-o, --output <format>  Output format: json, table, or compact (auto-detects from TTY)

Use with Claude Code (skill)

This repo doubles as a Claude Code plugin marketplace exposing the use-ixora skill, which teaches Claude how to drive the Ixora platform with this CLI — installing the stack, managing multiple instances (stack and external), running agents, inspecting traces, browsing knowledge, and more.

Via the ixora CLI (recommended):

ixora skills install          # add --global to install to your user directory
ixora skills install --agent claude-code cursor   # target specific coding agents
ixora skills update           # pick which installed skills to refresh (--global for user dir)

The skills ship inside the @ibm/ixora package, so ixora skills install installs them from your local install using the skills installer — no GitHub or repo access required. By default it auto-detects your coding agents; pass --agent to target specific ones. ixora skills list shows what it installs. ixora skills update re-syncs the installed skills from your current @ibm/ixora (upgrade the CLI to get newer skills) — it shows a picker of the installed Ixora skills (all pre-selected) and refreshes the ones you keep checked; add --yes to update them all non-interactively.

Via the Claude Code marketplace (requires access to the private ibmi-agi/ixora-cli repo):

claude plugin marketplace add ibmi-agi/ixora-cli
claude plugin install use-ixora@ixora-cli

Once installed, Claude activates the skill automatically based on context — e.g. "install ixora", "add a new ixora instance", "run an agent on prod", "inspect that trace" — or you can invoke it explicitly as /ixora-cli:use-ixora.

Development

git clone https://github.com/ibmi-agi/ixora-cli.git
cd ixora-cli
npm install
npm run build
npm link          # Makes 'ixora' available globally

npm test          # Run tests
npm run dev -- <command>  # Run without building

Legacy: Shell Script Version

The original ixora.sh shell script is still available in this repo for reference. To install it directly:

curl -LsSf https://raw.githubusercontent.com/ibmi-agi/ixora-cli/main/install.sh | sh

This installs the shell script to ~/.local/bin/ixora. The Node.js CLI above is the recommended version going forward. (The shell script does not include the AgentOS runtime commands — only the stack-management surface.)