FAQs

A collection of frequently asked questions along with explanations of common errors and how to resolve them.

1. General

Show Answer

Osmedeus is a workflow engine for security automation. It executes YAML-defined workflows with support for multiple execution environments (host, Docker, SSH), scheduling, and distributed scanning.

Hide Answer

The Osmedeus core engine is lightweight and can run anywhere with almost any specs.
However, if you plan to use it for reconnaissance (which is the main use case), it is recommended to use a modern Linux, macOS, or Windows system with WSL.
Since running reconnaissance generates heavy network traffic, it is also recommended to run Osmedeus in a cloud environment, such as a VM, Compute Engine, or EC2, to achieve the best performance.

Show Answer

# Build from source
make build

# Install to $GOBIN
make install

# Install security tools
osmedeus install binary --all

Show Answer

Yes of course. Osmedeus has built-in support for LLMs and you can use it in your workflow to do things like generating recon reports, writing custom scripts, or even building your own agentic workflow. You can check out the LLM Workflow Example to see how it works.Be aware that using LLMs may require you to have API keys for the LLM provider and may incur additional costs based on your usage. Always monitor your usage and costs when using LLMs in your workflows.Since Osmedeus is an orchestration framework, you can leverage it to coordinate your own custom AI/LLM tools including integrations like Claude Code or OpenCode directly within your YAML workflows. For instance, you could design a custom agent that invokes multiple tools as part of a defined pipeline and seamlessly plug it into your workflow. The flexibility is virtually unlimited.

Show Answer

Yes, I’ve built the osmedeus-expert skill at github.com/osmedeus/osmedeus-skills and you can use it in your agentic tool to writing YAML workflows, running CLI commands, and configuring advanced features.

2. Binary Installation

Hide Answer

Osmedeus is a standalone Golang binary and works perfectly fine on its own. However, when using Osmedeus to run YAML workflows for security automation, it often needs to call external tools like httpx, nuclei, ffuf, etc. These tools must be installed and available on your system for those workflows to function properly.

Hide Answer

Not all binaries listed in the registry are required for every workflow. Your scans may still function correctly even if some tools are missing.

Hide Answer

No. Installing all tools is completely optional. The registry includes additional tools that are commonly used in YAML workflows, but you only need the ones required for your specific workflow. Installing everything is not necessary for running a basic workflow.

Hide Answer

Like I said above, not all binaries listed in the registry are required for every workflow. Your scans may still function correctly even if some tools are missing.If you would like the ideal setup then I recommend using Docker to run Osmedeus and its workflows. This ensures that all dependencies are met and eliminates any compatibility issues. See the Docker Setup for more details.

3. Scan Execution & Scanning Results

Hide Answer

# Run a flow workflow
osmedeus run -f general -t example.com

# Run a module workflow
osmedeus run -m vulnerability-scan -t example.com

Hide Answer

# From command line
osmedeus run -f fast -t target1.com -t target2.com

# From file
osmedeus run -f fast -T targets.txt -c 5

Hide Answer

osmedeus run -m port-scan -t example.com --timeout 2h

Hide Answer

Results are stored in workspaces at ~/workspaces-osmedeus/<target>/.

Hide Answer

All you need to do is follow this guide to setup the token

Hide Answer

All you need to do is follow this guide to setup notification

Hide Answer

You can Join https://discord.gg/mtQG2FQsYA to see if anyone can help. I might answer from time to time but I couldn’t promise to answer every single of them.

Hide Answer

Nope, natively it doesn’t support proxy. But since the design of the tool is running other 3rd party tools and a lot of them don’t support proxy by default. I’ve already considered proxychains but it makes it extremely slow and breaks a lot of things.

Hide Answer

It will stay there because it got a sudo password prompt. Some special tools require root permission to run like nmap. Make sure you allow nmap can be run without sudo password prompt.

Hide Answer

It’s probably because the thing you put in was really big. Think about trying to run the content discovery against 2000 different hosts. That’s why it takes a long time.

Hide Answer

Again it very much depends on your target. Osmedeus really shines on large scope targets, not the single intentionally vulnerable web app. Just scan some random VDP then you will see the result. The reason it won’t find any vulnerability on the intentionally vulnerable app is the vulnscan module won’t support it. But you’re always welcome to customize the workflow to do so.

Hide Answer

Yes, just follow this guide to add it to your workflow.

Hide Answer

Read the flow and module files to determine what a step actually runs
Seriously, read the flow and module files.
Remember that you were warned twice about reading the flow and module files.
Search for the tool command in the workflow folder to confirm whether it is used or not (e.g: rg -F 'nuclei' ~/osmedeus-base/workflows/)

Hide Answer

Please refer to this page to start a web server and get credentials. You may need to run this command osmedeus config view server.password

Hide Answer

The simplest way to do it is running the process under https://tmuxcheatsheet.com/ . Other than that you can setup a service to run the osmedeus web server as a background process.

Hide Answer

Read the vulnerability X description.
Seriously, read the vulnerability X description.
Remember that you were warned twice about reading the vulnerability X description.
Search for that vulnerability X name.
Manually verify the vulnerability X.
Still no results? maybe https://letmegooglethat.com/?q=what+is+a+vulnerability+X can help you.

Hide Answer

It is often the case that the availability of a subdomain found during a scan may not be the same when you attempt to manually verify it. This depends on the target and can vary.

Hide Answer

Yes, it’s normal for certain commands to exhibit expected exit statuses, as they may succeed under specific conditions. However, if you’re confident that the raw bash command should succeed but is failing, please try copying the raw bash command and investigate why it’s encountering issues.

Hide Answer

You can run osmedeus workflow ls or osmedeus workflow show <workflow-name> --verbose to see the description and that would fit to the scan

Hide Answer

This is likely due to the fact that the workflow you executed did not generate any assets. You can verify this by checking the workspace directory located at ~/workspaces-osmedeus/<target>/ to see if any files were created.It is also because the workflow doesn’t use any database utility function to save the assets into the database. You can check the workflow file to see if it uses any database utility functions like db_import_asset. You can also see the full list of database related function at osmedeus func ls db --example

Hide Answer

This is likely due to the fact that the workflow you executed did not generate any assets. You can verify this by checking the workspace directory located at ~/workspaces-osmedeus/<target>/ to see if any files were created.It is also because the workflow doesn’t use any notification utility function to save the assets into the notification. You can check the workflow file to see if it uses any notification utility functions like notify_telegram. You can also see the full list of notification related function at osmedeus func ls noti --example

4. Workflows

Hide Answer

Module: A single workflow unit containing steps that execute sequentially
Flow: Orchestrates multiple modules, allowing parallel execution and dependencies between modules

Hide Answer

Workflows are stored in ~/osmedeus-base/workflows/:

flows/ - Flow workflows
modules/ - Module workflows

Hide Answer

Create a YAML file in the workflows directory:

name: my-workflow
kind: module
description: My custom workflow
params:
  - name: target
    required: true
steps:
  - name: scan-target
    type: bash
    command: nmap {{target}}

Hide Answer

Type	Description
`bash`	Execute shell commands
`function`	Execute JavaScript utility functions
`parallel-steps`	Run steps concurrently
`foreach`	Iterate over items
`remote-bash`	Execute in Docker or via SSH
`http`	Make HTTP requests
`llm`	Execute LLM API calls
`agent`	Agentic LLM execution with tool calling

5. API & Server

Hide Answer

osmedeus server

The server starts on port 8002 by default.

Hide Answer

$ osmedeus server
2026-02-16T22:59:11+07:00 ERROR Failed to create server {"error": "failed to run database migrations: failed to create index: SQL logic error: no such column: webhook_uuid (1)"}
Error: failed to run database migrations: failed to create index: SQL logic error: no such column: ... (1)

Error like this means that the database schema is outdated and the server cannot start. To fix this, you can run osmedeus db clean --force to clean up the database and then start the server again. This will reset your database, so make sure to backup any important data before running the command.

Hide Answer

# Get a JWT token
curl -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "osmedeus", "password": "admin"}'

# Use the token
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer <token>"

Hide Answer

osmedeus server --no-auth

Hide Answer

Yes, enable API key authentication in the server configuration. Then use the X-API-Key header instead of Authorization: Bearer.

6. Scheduling

Hide Answer

# Via CLI (creates a cron schedule)
osmedeus run -f subdomain-enum -t example.com --schedule "0 2 * * *"

# Via API
curl -X POST http://localhost:8002/osm/api/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-scan",
    "workflow_name": "subdomain-enum",
    "target": "example.com",
    "schedule": "0 2 * * *"
  }'

Hide Answer

Standard 5-field cron: minute hour day-of-month month day-of-weekExamples:

0 2 * * * - Daily at 2 AM
0 0 * * 0 - Weekly on Sunday
*/30 * * * * - Every 30 minutes

7. Runners

Hide Answer

Runner	Description
`host`	Execute on local machine (default)
`docker`	Execute in Docker containers
`ssh`	Execute on remote machines via SSH

Hide Answer

osmedeus run -m port-scan -t example.com --runner docker --docker-image osmedeus/osmedeus:latest

Hide Answer

osmedeus run -m port-scan -t example.com --runner ssh --ssh-host worker.example.com

8. Distributed Mode

Hide Answer

Start the master:

osmedeus server --master

Join workers:

osmedeus worker join --master http://master:8002

Hide Answer

curl -X POST http://localhost:8002/osm/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_name": "subdomain-enum",
    "target": "example.com"
  }'

9. Troubleshooting

Hide Answer

osmedeus install binary --all --check

Hide Answer

# Install specific tools
osmedeus install binary --name nuclei --name httpx

# Install all tools
osmedeus install binary --all

Hide Answer

Logs are stored in the workspace:

cat ~/osmedeus-base/workspaces/<target>/log/execution.log

Hide Answer

osmedeus snapshot export <workspace>

Hide Answer

osmedeus snapshot import snapshot.zip

10. Configuration

Hide Answer

~/osmedeus-base/osm-settings.yaml

Hide Answer

Edit osm-settings.yaml:

server:
  port: 9000

Or use the --port flag:

osmedeus server --port 9000

Hide Answer

Edit osm-settings.yaml:

database:
  db_engine: sqlite3  # or postgres
  host: localhost
  port: 5432
  name: osmedeus
  username: user
  password: pass

11. Clean up & Uninstall

Hide Answer

just run the command below to clean up workspace and database and generate the default osmedeus config

rm -rf ~/osmedeus-base ~/workspaces-osmedeus
osmedeus install base --preset

Hide Answer

just run the command below to clean up workspace and database and generate the default osmedeus config

rm -rf ~/workspaces-osmedeus
osmedeus db clean --force

Hide Answer

just run the command below

rm -rf ~/.osmedeus ~/osmedeus-base ~/workspaces-osmedeus
rm -rf $(which osmedeus)

Getting Started

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

1. General

2. Binary Installation

3. Scan Execution & Scanning Results

4. Workflows

5. API & Server

6. Scheduling

7. Runners

8. Distributed Mode

9. Troubleshooting

10. Configuration

11. Clean up & Uninstall

​1. General

​2. Binary Installation

​3. Scan Execution & Scanning Results

​4. Workflows

​5. API & Server

​6. Scheduling

​7. Runners

​8. Distributed Mode

​9. Troubleshooting

​10. Configuration

​11. Clean up & Uninstall

1. General

2. Binary Installation

3. Scan Execution & Scanning Results

4. Workflows

5. API & Server

6. Scheduling

7. Runners

8. Distributed Mode

9. Troubleshooting

10. Configuration

11. Clean up & Uninstall