runyx 1.0.1

Local bridge for Runyx extension

Runyx Project Overview

This repository contains Runyx, a browser automation platform composed of a Chromium extension and a local Python runtime used for development, testing, and orchestration.

At a high level:

• The Chromium extension provides the Automation Studio UI and executes automations in the browser.
• The Runyx Bridge is a lightweight local server (HTTP + WebSocket) used during development.
• The Runyx App (Runner) is an object-oriented Python entrypoint that:
  • starts the Bridge
  • launches Edge or Chrome via Selenium (non-headless)
  • loads the extension
  • imports a project JSON on startup (from extension/local/import.json)
  • activates the extension via hotkey

Each component can be used independently, but together they form the full local Runyx development experience.

---

Repository structure

/
extension/          # Chromium extension (runtime + UI)
runyx_bridge/       # Python bridge + runner (MVP)
README.md           # <- this file

Each main folder has its own README with deeper details:

• extension/README.md - extension usage and UI
• runyx_bridge/README.md - Python bridge and runner details
• examples/README.md

This root README explains how everything fits together.

---

Core components

1) Chromium extension

The extension contains:

• Runtime
  • Service Worker
  • Content Script
  • Bridge between UI and page context
• Automation Studio UI
  • Built with Next.js
  • Embedded into the extension
  • Also available inside DevTools

The extension is responsible for:

• Managing workflows, triggers, and steps
• Executing DOM actions (click, type, wait, extract, screenshot, etc.)
• Collecting artifacts (cookies, page source, screenshots)
• Communicating with Runyx Bridge (HTTP + WebSocket)

Load it locally via:

chrome://extensions -> Developer mode -> Load unpacked -> extension/

For Edge:

edge://extensions -> Developer mode -> Load unpacked -> extension/

The UI can be opened via:

• Extension icon
• Ctrl + Shift + F
• DevTools tab ("Runyx")

---

2) Runyx Bridge (MVP)

Runyx Bridge is a development-only Python library that exposes:

• HTTP server
  • Receives data from the extension
  • Endpoints are defined via decorators
  • CORS is fully open (by design)
• WebSocket server
  • Used only as a trigger source
  • Emits events that start workflows in the extension

Key characteristics:

• Minimal by design (MVP)
• No authentication
• No persistence
• No production guarantees

It exists solely to support local development and testing.

See full details in runyx_bridge/README.md.

---

3) Runyx App (Python Runner)

The Runyx App is the orchestration layer that ties everything together.

It is responsible for:

1. Starting Runyx Bridge (HTTP + WebSocket)
2. Launching Edge or Chrome using Selenium in non-headless mode
3. Loading the Runyx extension (unpacked)
4. Importing a project JSON from extension/local/import.json
5. Sending the activation hotkey (Ctrl + Shift + F)
6. Keeping the environment alive (server mode) or exiting cleanly

This makes it possible to:

• Start the entire Runyx stack with a single Python script
• Test the extension without manual browser setup
• Automate local development flows

---

Typical local development flow

1. Start Runyx using the Python runner
2. Edge/Chrome opens normally (non-headless)
3. The Runyx extension is loaded automatically
4. The project JSON is imported into storage
5. The extension UI is activated via hotkey
6. Automation Studio is ready to use
7. HTTP + WebSocket endpoints are available locally

---

Example: minimal runner usage

from runyx_bridge import RunyxApp

app = RunyxApp(
    extension_path="./extension",
    import_project_path="./my-first-project-project.json",
    require_import=True,
    requests=True,
    websocket=True,
    on_background=False,  # server mode
)

app.start()

---

Using Runyx Bridge standalone

The Bridge can also be used without Selenium if you prefer to:

• open Edge or Chrome manually
• load the extension yourself
• trigger workflows via WebSocket
• receive data via HTTP

Example:

from runyx_bridge import run, receive

@receive("/receive")
def handle_data(payload, meta):
    print(payload)
    return "ok"

run(requests=True, websocket=True, on_background=False)

---

How communication works (high level)

• WebSocket
  • External systems Bridge Extension
  • Used only for triggers
• HTTP
  • Extension Bridge
  • Used for screenshots, cookies, page source, extracts, etc.

The extension always remains the execution authority.

---

Installation (Python side)

This project is intended to be used in editable / development mode.

Using Poetry (recommended):

poetry install
poetry run pytest

Or using pip:

pip install -e .

---

Important notes

• Runyx Bridge is not production software
• CORS is fully open intentionally
• Selenium runs Edge or Chrome non-headless
• Hotkey activation depends on OS window focus
• The extension can also be used manually without the runner
• Project data is imported on startup from extension/local/import.json

---

Documentation map

• README.md (this file) - project overview
• extension/README.md - extension usage and UI
• extension/documentation/README.md - architecture and internals
• runyx_bridge/README.md - Python bridge and runner details
• examples/README.md -> runnable bridge/runner examples

---

Project goal

Provide a clear, minimal, and hackable local environment for developing and testing browser automations using the Runyx Chromium extension.

Nothing more, nothing less.