Skip to main content
Start the REST API server and manage workers.

​
Synopsis

osmedeus server [flags]
osmedeus worker <command> [flags]

​
server

Start the REST API server. 
osmedeus server [flags]
Aliases: serve

​
Flags

FlagDescription
--host <address>Bind address (default from config)
--port <port>Listen port (default from config)
-A, --no-authDisable authentication (dev only)
--masterRun as distributed master node
--redis-url <url>Redis URL for distributed mode

​
Examples

# Start with defaults
osmedeus server

# Custom host and port
osmedeus server --host 0.0.0.0 --port 8080

# Disable authentication (development only)
osmedeus server -A

# Start as distributed master
osmedeus server --master

# Master with custom Redis
osmedeus server --master --redis-url redis://redis-host:6379

​
Output

$ osmedeus server
Starting Osmedeus Server...
  Host: 0.0.0.0
  Port: 8002
  Auth: enabled

Server endpoints:
  - API: http://localhost:8002/osm/api/
  - Swagger: http://localhost:8002/swagger/
  - Health: http://localhost:8002/health

Press Ctrl+C to stop

​
Endpoints

EndpointDescription
/healthHealth check
/health/readyReadiness probe
/server-infoServer information
/swagger/*API documentation
/osm/api/*API endpoints (auth required)
/ws/{prefix}/*Workspace files

​
worker join

Join as a distributed worker. 
osmedeus worker join [flags]

​
Flags

FlagDescription
--redis-url <url>Redis URL override

​
Examples

# Join with default Redis
osmedeus worker join

# Join with custom Redis
osmedeus worker join --redis-url redis://redis-host:6379

​
Output

$ osmedeus worker join
Joining worker pool...
  Redis: redis://localhost:6379
  Worker ID: worker-abc123

✓ Connected to master
Waiting for tasks...

​
worker status

Check worker pool status. 
osmedeus worker status [flags]

​
Output

$ osmedeus worker status
Worker Pool Status:

Master: redis://localhost:6379
Connected Workers: 3

┌─────────────────┬────────────┬───────────┬─────────────────────┐
│ Worker ID       │ Status     │ Tasks     │ Last Seen           │
├─────────────────┼────────────┼───────────┼─────────────────────┤
│ worker-abc123   │ idle       │ 15        │ 2024-01-15 14:30:00 │
│ worker-def456   │ busy       │ 23        │ 2024-01-15 14:30:05 │
│ worker-ghi789   │ idle       │ 12        │ 2024-01-15 14:29:55 │
└─────────────────┴────────────┴───────────┴─────────────────────┘

Queue: 2 pending tasks

​
health

Check server or worker health. 
osmedeus health [flags]

​
Examples

# Check local server health
osmedeus health

# Check remote server
osmedeus health --host http://remote:8002

​
Output

$ osmedeus health
Server Health Check:

✓ API Server: healthy
✓ Database: connected
✓ Workflows: 12 loaded
✓ Binaries: 15/20 available

Status: healthy

​
Distributed Mode

​
Architecture

┌─────────────────┐     ┌─────────────────┐
│     Master      │     │     Redis       │
│   (API Server)  │────▶│   (Task Queue)  │
└─────────────────┘     └────────┬────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
        ▼                        ▼                        ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Worker 1    │       │   Worker 2    │       │   Worker N    │
└───────────────┘       └───────────────┘       └───────────────┘

​
Setup

  1. Start Redis: 
    docker run -d -p 6379:6379 redis:7-alpine
  2. Start master: 
    osmedeus server --master
  3. Start workers (on each machine): 
    osmedeus worker join --redis-url redis://master-host:6379
  4. Submit distributed scans: 
    osmedeus run -f general -t example.com -D

​
API Endpoints (Master Mode)

EndpointDescription
GET /osm/api/workersList workers
GET /osm/api/workers/:idWorker details
GET /osm/api/tasksList tasks
GET /osm/api/tasks/:idTask details
POST /osm/api/tasksSubmit task

​
Authentication

​
Default Credentials

Configure in osm-settings.yaml: 
server:
  username: osmedeus
  password: [REDACTED:password]

​
Get Token

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

​
Use Token

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

​
Configuration

Server settings in osm-settings.yaml: 
server:
  host: "0.0.0.0"
  port: 8002
  ui_path: "{{base_folder}}/ui/"
  workspace_prefix: ""      # Auto-generated
  username: osmedeus
  password: [REDACTED:password]

redis:
  url: "redis://localhost:6379"
  password: ""
  db: 0

​
Docker Deployment

​
Single Server

docker run -d \
  --name osmedeus \
  -p 8002:8002 \
  -v osmedeus-data:/root/osmedeus-base \
  osmedeus:latest server

​
Distributed (Docker Compose)

version: '3.8'
services:
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

  master:
    image: osmedeus:latest
    command: server --master
    ports: ["8002:8002"]
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on: [redis]

  worker:
    image: osmedeus:latest
    command: worker join
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on: [redis, master]
    deploy:
      replicas: 3

​
Notes

  • Use --no-auth only for development
  • Master mode requires Redis
  • Workers auto-reconnect on connection loss
  • Graceful shutdown on SIGINT/SIGTERM

​
See Also