Osmedeus

What is Osmedeus? Copy Chapter

Osmedeus is a security focused declarative orchestration engine that simplifies complex workflow automation into auditable YAML definitions, complete with encrypted data handling, secure credential management, and sandboxed execution.

Built for both beginners and experts, it delivers powerful, composable automation without sacrificing the integrity and safety of your infrastructure.

Key Features Copy Chapter

• Declarative YAML Workflows - Define pipelines with hooks, decision routing, module exclusion, and conditional branching across multiple runners (host, Docker, SSH)
• Distributed Execution - Redis-based master-worker pattern with queue system, webhook triggers, and file sync across workers
• Rich Function Library - 80+ utility functions including nmap integration, tmux sessions, SSH execution, TypeScript/Python scripting, SARIF parsing, and CDN/WAF classification
• Event-Driven Scheduling - Cron, file-watch, and event triggers with filtering, deduplication, and delayed task queues
• Agentic LLM Steps - Tool-calling agent loops with sub-agent orchestration, memory management, and structured output; plus ACP subprocess agents (Claude Code, Codex, OpenCode, Gemini)
• Cloud Infrastructure - Provision and run scans across DigitalOcean, AWS, GCP, Linode, and Azure with cost controls and automatic cleanup
• Rich CLI Interface - Interactive database queries, bulk function evaluation, workflow linting, progress bars, and comprehensive usage examples
• REST API & Web UI - Full API server with webhook triggers, database queries, and embedded dashboard for visualization

See Documentation Page for more details.

Installation Copy Chapter

curl -sSL http://www.osmedeus.org/install.sh | bash

[npm](https://www.npmjs.com/package/@j3ssie/osmedeus) Copy Section

npm install @j3ssie/osmedeus

Ships prebuilt binaries for linux and macOS on x64/arm64.

See Quickstart for quick setup and Installation for advanced configurations.

☁️ Sponsor — Bloome Copy Chapter

Automating recon with Osmedeus? Bloome brings that same team-of-agents mindset to the rest of your workflow: multiple AI agents (Claude, ChatGPT, DeepSeek and more) in one shared chat that split the work, hand off tasks, cross-check each other, and refine the output until it's right — triage findings, draft reports, and run scheduled checks together. Zero setup, in the cloud, on web and mobile, and shareable with your team. 👉 Try Bloome

Quick Start Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Docker Copy Chapter

# Show help
docker run --rm j3ssie/osmedeus:latest --help

# Run a scan
docker run --rm -v $(pwd)/output:/root/workspaces-osmedeus \
    j3ssie/osmedeus:latest run -f general -t example.com

For more CLI usage and example commands, refer to the CLI Reference.

High-Level Architecture Copy Chapter

┌───────────────────────────────────────────────────────────────────────────┐
│                   Osmedeus Orchestration Engine                           │
├───────────────────────────────────────────────────────────────────────────┤
│  ENTRY POINTS                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐                │
│  │   CLI    │  │ REST API │  │Scheduler │  │ Distributed │                │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬───────┘                │
│       └─────────────┴─────────────┴──────────────┘                        │
│                              │                                            │
│                              ▼                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │ CONFIG ──▶ PARSER ──▶ EXECUTOR ──▶ STEP DISPATCHER ──▶ RUNNER       │  │
│  │                          │                                          │  │
│  │  Step Executors: bash | function | parallel | foreach | remote-bash │  │
│  │                  http | llm | agent | agent-acp | SARIF/SAST       │  │
│  │  Hooks: pre_scan_steps → [main steps] → post_scan_steps             │  │
│  │                          │                                          │  │
│  │  Runners: HostRunner | DockerRunner | SSHRunner                     │  │
│  │  Queue: DB + Redis polling → dedup → concurrent execution           │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────┘

For more information about the architecture, refer to the Architecture Documentation.

Roadmap and Status Copy Chapter

The high-level ambitious plan for the project, in order:

Documentation Copy Chapter

Disclaimer Copy Chapter

Osmedeus is designed to execute arbitrary code and commands from user supplied input via CLI, API, and workflow definitions. This flexibility is intentional and central to how the engine operates.

Please refer to the ⚠️ Security Warning page for more information on how to stay safe. SECURITY.md draws the line between the code execution that is intentional and what counts as a vulnerability, and is where to start if you want to report one.

Think twice before you:

• Run workflows downloaded from untrusted sources
• Execute commands or scans against targets you don't own or have permission to test
• Use workflows without reviewing their contents first

You are responsible for what you run. Always review workflow YAML files before execution, especially those obtained from third parties.

License Copy Chapter

Osmedeus is made with ♥ by @j3ssie and it is released under the MIT license.