Getting Started

Quickstart

Get Obvionx running in under 5 minutes. A single binary, no dependencies, and your site is protected with AI-powered bot detection.

Single Binary

No runtime dependencies

Self-Hosted

100% on your server

<0.1ms Latency

Sub-millisecond inference

Download & Run

terminal

1# Download from your dashboard after purchase
2# Then make it executable
3chmod +x obvionx-linux-x64
4 
5# Run the engine
6./obvionx-linux-x64 config.toml

Add the Sensor

Add one line to your website's <head> tag:

index.html

<script src="/_secu/sensor.js" async></script>

Point to Origin

config.toml

1[proxy]
2target = "http://localhost:3000"
3dashboard_port = 9080

You're done!

Your site is now protected. Visit http://localhost:9080 to view the real-time dashboard.

Installation

Complete step-by-step guide to set up Obvionx from scratch.

Available Platforms

Linux x64

obvionx-engine-linux-x64

Linux ARM64

obvionx-engine-linux-arm64

macOS (Apple Silicon)

obvionx-engine-darwin-arm64

macOS (Intel)

obvionx-engine-darwin-x64

Windows x64

obvionx-engine-windows-x64.exe

Step-by-Step Setup

Create project folder & download binary

terminal

1mkdir obvionx
2cd obvionx
3 
4# Download the binary from your profile page
5# Then make it executable (Linux/macOS)
6chmod +x obvionx-engine-darwin-arm64

Download pre-trained models from HuggingFace

Clone the models repository from HuggingFace:

terminal

1# Option 1: Clone with git (requires git-lfs)
2git lfs install
3git clone https://huggingface.co/obvionx/obvionx-models models
4 
5# Option 2: Download manually
6mkdir models
7cd models
8# Download each file from: https://huggingface.co/obvionx/obvionx-models/tree/main
9# Files needed: bot.bin, ddos.bin, fraud.bin, router.bin, scraper.bin

💡 Or download directly: huggingface.co/obvionx/obvionx-models

Create config.toml

Create a config.toml file. See the Configuration section for the complete reference.

Add your license.key

Download your license file from the Profile page and save it as license.key in your project folder.

Run the engine

terminal

1./obvionx-engine-darwin-arm64
2 
3# Expected output:
4#     ____  _          _                     
5#    / __ \| |____   _(_) ___  _ __ __  __
6#   | |  | | '_ \ \ / / |/ _ \| '_ \\ \/ /
7#   | |__| | |_) \ V /| | (_) | | | |>  < 
8#    \____/|_.__/ \_/ |_|\___/|_| |_/_/\_\
9#
10# INFO obvionx_engine: Obvionx v1.0.0
11# INFO obvionx::config: Loaded configuration from config.toml
12# INFO obvionx::license: ✓ License valid for user_xxx (expires 2026-01-31)
13# INFO obvionx_engine: Starting Obvionx on 0.0.0.0:8080
14# INFO obvionx::moe: 📂 Loaded MoE models from "models"
15# INFO obvionx_engine: 📊 Dashboard listening on 0.0.0.0:9080

Final Folder Structure

folder structure

1obvionx/
2├── obvionx-engine-darwin-arm64   # Binary (or linux-x64, etc.)
3├── config.toml                    # Configuration file
4├── license.key                    # Your license file
5└── models/
6    ├── bot.bin
7    ├── ddos.bin
8    ├── fraud.bin
9    ├── router.bin
10    └── scraper.bin

You're ready!

Visit http://localhost:9080 to view your dashboard and http://localhost:8080 for the protected proxy.

Configuration

Complete configuration reference:

config.toml

1# Obvionx Configuration
2 
3# Server settings
4host = "0.0.0.0"
5port = 8080
6 
7# Thresholds for decision making
8[thresholds]
9sensitivity = 1.0    # Detection multiplier (0.5-2.0)
10monitor = 0.3        # Log for review
11challenge = 0.6      # Show challenge
12block = 0.8          # Block request
13 
14# Proxy configuration
15[proxy]
16mode = "reverse_proxy"                # "api_only" or "reverse_proxy"
17upstream = "http://localhost:3000"    # Your backend URL
18inject_sensor = true                  # Auto-inject sensor script
19dashboard_port = 9080                 # Dashboard on separate port
20 
21# Learning settings
22[learning]
23baseline_samples = 1000
24initial_learning_rate = 0.001
25decay_factor = 0.9999
26min_learning_rate = 0.00001
27max_samples_per_window = 1000
28rate_limit_window_secs = 60
29 
30# Session settings
31[session]
32ttl_secs = 1800
33max_sessions = 10000
34aggregation_window = 10
35 
36# MoE (Mixture of Experts) settings
37[moe]
38enabled = true
39router_hidden_dim = 8
40router_threshold = 0.2
41max_active_experts = 2
42fallback_to_bot = true
43enable_ddos_expert = true
44models_dir = "models"
45 
46# License
47[license]
48key_file = "license.key"
49 
50# Cloud API Configuration (optional)
51[cloud]
52enabled = false                       # Set true to enable cloud reporting
53endpoint = "https://api.obvionx.com"
54api_key = ""                          # Your API key (sk-ob-xxx)
55report_interval_secs = 5
56engine_name = "My Engine"
57 
58# DDoS Protection
59[ddos]
60enabled = true
61ip_rate_limit = 100
62ip_rate_window_secs = 60
63ip_ban_duration_secs = 300
64global_rate_limit = 10000
65protection_mode_threshold = 0.8
66auto_blacklist_enabled = true
67auto_blacklist_duration_secs = 3600

JavaScript Sensor

The sensor collects behavioral signals to distinguish humans from bots:

Mouse Movement

Tracks natural cursor patterns

Scroll Behavior

Monitors scroll velocity and patterns

Click Timing

Analyzes click intervals and positions

Keyboard Input

Detects human typing rhythms

Auto-Inject (Recommended)

When inject_sensor = true in your config, Obvionx automatically injects the sensor script into all HTML responses. No code changes needed!

config.toml

[proxy]
inject_sensor = true   # Automatically adds sensor to HTML pages

Manual Installation

If you prefer to add the sensor manually (or auto-inject is disabled), add this to your HTML <head>:

index.html

<script src="/_secu/sensor.js" async></script>

Zero Config Setup

With inject_sensor = true, you don't need to modify any code. The sensor is automatically added to every HTML page that passes through Obvionx. This is the recommended approach for most users.

Understanding Thresholds

Score	Action	Description
0.0 – 0.3	Allow	Normal traffic, passes through
0.3 – 0.6	Monitor	Logged for review, allowed
0.6 – 0.8	Challenge	CAPTCHA or proof-of-work
0.8 – 1.0	Block	Request denied, 403 response

Warning

Start with higher thresholds (0.7/0.85/0.95) and gradually lower them as the model learns your traffic patterns to avoid false positives.

API Reference

GET/obvionx/status

Returns engine health and metrics.

response.json

1{
2  "status": "healthy",
3  "uptime_secs": 86400,
4  "requests_processed": 1500000,
5  "bots_blocked": 23400,
6  "learning_state": "stable",
7  "model_version": "1.0.0"
8}

POST/obvionx/control

Control learning behavior.

terminal

1# Freeze learning (production safety)
2curl -X POST http://localhost:8080/obvionx/control \
3  -H "Content-Type: application/json" \
4  -d '{"action": "freeze"}'
5 
6# Resume learning
7curl -X POST http://localhost:8080/obvionx/control \
8  -d '{"action": "unfreeze"}'

MoE Neural Network

Obvionx uses a Mixture of Experts architecture for specialized threat detection:

                ┌─────────────┐
                │   Request   │
                └──────┬──────┘
                       │
                ┌──────▼──────┐
                │   Router    │  ← Selects experts
                │   (7→8→4)   │
                └──────┬──────┘
                       │
       ┌───────┬───────┼───────┬───────┐
       ▼       ▼       ▼       ▼       ▼
      ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
      │ Bot  │ │ DDoS │ │Scrape│ │Fraud │
      │7→28→8│ │16→32→8│|7→28→8│ │7→28→8│
      └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
         └------──┴───┬──-─┴───────-┘
                      ▼
                ┌─────────────┐
                │ Final Score │
                └─────────────┘

Each expert is an autoencoder trained to reconstruct "normal" patterns. High reconstruction error = anomaly = likely bot.

DDoS Protection

The DDoS expert analyzes 16 signals beyond rate limiting:

Path-aware rate limiting

Different limits for /login, /api, static assets

Datacenter IP detection

Identifies AWS, GCP, Azure, DigitalOcean IPs

Request diversity

Detects single-path hammering vs browsing

User-agent analysis

Multiple UAs from same IP = suspicious

Learning System

Obvionx continuously learns from your traffic with built-in safety:

Cold

Warm

Stable

Frozen

Poisoning Defense

The engine includes automatic poisoning defense that validates learning samples and rejects outliers that could corrupt the model.

Installation