ORCS CLI

Lua-extensible Agentic Shell for building AI-powered development tools.

ORCS (Orchestrated Runtime Component System) provides a component-based architecture where every behavior is implemented as a Lua script, capability-gated, and sandboxed.

Part of the ORCS family — a suite of multi-agent AI tools built around orchestrated reasoning and collaboration. See also ORCS Desktop for the GUI workspace application.

Prerequisites

• Rust 1.80.0 or later

Features

• Lua-first extensibility -- All components (agents, skills, tools) are Lua scripts
• Capability-gated APIs -- LLM, HTTP, exec, file I/O each require explicit capability grants
• Sandbox isolation -- Path traversal prevention, Lua stdlib restrictions, input sanitization
• Multi-provider LLM -- Ollama, OpenAI, Anthropic via config.toml
• ActionIntent system -- Unified tool dispatch with IntentRegistry, LLM tool_use auto-resolution, and dynamic intent registration
• Skill recommendation -- LLM-based or keyword-based skill matching with automatic tool registration
• Session persistence -- Pause/resume with component state snapshot
• Hook system -- FQL-based lifecycle hooks for pre/post processing
• Human-in-the-loop -- Approval workflows for destructive operations

Install

cargo install orcs-cli

Or from source:

cargo build --release
# Binary at target/release/orcs

Quick Start

Run with default builtins

orcs

Run with verbose output

orcs --verbose

Run in sandbox mode (isolated environment)

orcs --sandbox

Resume a previous session

orcs --resume <SESSION_ID>

Create a Lua component

-- ~/.orcs/components/hello.lua
return {
    id = "hello",
    namespace = "custom",
    subscriptions = {"Hello"},

    init = function(cfg)
        orcs.log("info", "Hello component initialized")
    end,

    on_request = function(request)
        if request.operation == "greet" then
            local name = request.payload or "world"
            return { success = true, data = "Hello, " .. name .. "!" }
        end
        return { success = false, error = "unknown operation" }
    end,

    on_signal = function(sig)
        return "Handled"
    end,

    shutdown = function()
        orcs.log("info", "Goodbye")
    end,
}

Add it to config.toml:

[components]
load = ["agent_mgr", "skill_manager", "hello"]

CLI

orcs [OPTIONS] [COMMAND]...

Lua API

File I/O (Sandbox-gated)

Execution (Capability::EXECUTE)

LLM (Capability::LLM)

LLM opts support tools (default true), resolve (default false), and max_tool_turns (default 10) for automatic tool_use dispatch.

Intent Dispatch

HTTP (Capability::HTTP)

Component Communication

Child Management

Serialization & Utilities

Configuration

Create config.toml in your project root (or ~/.orcs/config.toml for global):

[components]
load = ["agent_mgr", "skill_manager", "profile_manager", "foundation_manager", "console_metrics", "shell", "tool"]

[components.settings.agent_mgr]
llm_provider = "ollama"
llm_model = "llama3.2:latest"
llm_base_url = "http://localhost:11434"
# llm_api_key = ""         # for openai/anthropic
prompt_placement = "both"   # "top" | "both" | "bottom"

[components.settings.skill_manager]
recommend_skill = true
# recommend_llm_provider = "ollama"
# recommend_llm_model = "llama3.2:latest"

[hil]
auto_approve = false
timeout_ms = 30000

[ui]
verbose = false
color = true

[[hooks.hooks]]
id = "audit"
fql = "builtin::*"
point = "request.pre_dispatch"
script = "hooks/audit.lua"

Builtin Components

Architecture

Layer 4: Frontend
  orcs-cli --- main.rs, Args, CliConfigResolver, --sandbox

Layer 3: Application
  orcs-app --- OrcsApp, OrcsAppBuilder, builtins expansion

Layer 2: Runtime (Internal)
  orcs-runtime --- Engine, Channel, World, Config, Session, Sandbox, IO

Layer 1.5: Hooks
  orcs-hook --- HookDef, HooksConfig, FQL-based lifecycle hooks

Layer 1: Plugin SDK
  orcs-component --- Component, Child, Agent, Skill traits
  orcs-event --- Signal, Request, Response
  orcs-types --- ComponentId, ActionIntent, IntentDef, IntentRegistry
  orcs-auth --- Capability, Permission, SandboxPolicy

Plugin Implementation:
  orcs-lua --- LuaComponent, LuaChild, orcs.* API, IntentRegistry, ScriptLoader

Dev Tools:
  orcs-lint --- Architecture lint (OL002: no unwrap, layer dependency checks)

Documentation

API documentation is generated from source via rustdoc. Each crate has module-level documentation with architecture diagrams, usage examples, and security notes.

cargo doc --workspace --no-deps --open

Contributing

Bug reports, feature requests, and questions are welcome via GitHub Issues.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.