🚀 AutoMesh Documentation

A professional integration guide for building browser automation, API-driven workflows, AI-assisted agents, plugins and production-ready automation systems with AutoMesh.

📦 Installation

Create an isolated Python environment and install the AutoMesh SDK or your selected integrations.

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip

# Install the AutoMesh SDK when it is available from your official package source
pip install automesh

🏗️ Platform Architecture

A scalable AutoMesh workflow can be organized into five layers:

✅ Quick Start

import os
import requests

api_key = os.environ["AUTOMESH_API_KEY"]

response = requests.post(
    "https://api.example.com/v1/jobs",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"workflow": "example-workflow"}
)

print(response.json())

🧪 Connect AutoMesh with Selenium

Use Selenium when your project already depends on WebDriver, browser profiles or an existing Selenium test/automation stack. AutoMesh can act as the orchestration layer around the driver rather than replacing Selenium.

from selenium import webdriver
from selenium.webdriver.common.by import By

options = webdriver.ChromeOptions()
driver = webdriver.Chrome(options=options)

driver.get("https://example.com")
title = driver.find_element(By.TAG_NAME, "h1").text

# Pass validated data to your AutoMesh workflow/API
print(title)

driver.quit()

Recommended integration boundary

Keep browser control in Selenium and pass normalized events, extracted content and job results to AutoMesh. This separation makes it easier to replace Selenium without rewriting your business logic.

🎭 Connect AutoMesh with Playwright

Playwright is well suited to modern browser automation where isolated contexts, multiple pages and async workflows are useful.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto("https://example.com")

    result = {
        "title": page.title(),
        "url": page.url
    }

    # Send `result` to an AutoMesh workflow when required.
    print(result)
    browser.close()

🧭 Connect AutoMesh with DrissionPage

DrissionPage can be documented as an optional browser/session adapter for projects that prefer its API. Keep the AutoMesh workflow interface independent of any single browser library.

# Example adapter pattern
from DrissionPage import ChromiumPage

page = ChromiumPage()
page.get("https://example.com")

data = {
    "title": page.title,
    "url": page.url
}

print(data)

🦊 Firefox Support

Firefox can be used through a supported automation framework such as Selenium or Playwright. Select Firefox explicitly in your browser configuration and keep browser-specific capabilities separate from the core workflow.

from selenium import webdriver

options = webdriver.FirefoxOptions()
driver = webdriver.Firefox(options=options)

driver.get("https://example.com")
print(driver.title)
driver.quit()

🔄 Dual / Hybrid Browser Workflows

A dual workflow means different components handle different responsibilities. For example, one browser session may perform an interactive task while an API client or second browser context processes independent data.

Do not rely on undocumented copying of credentials or protected session data between browsers. Use explicit, authorized authentication and documented session handling.

🤖 AI & LLM Integration

AutoMesh can use an LLM layer for tasks such as classifying page content, extracting structured information, choosing among approved tools and generating workflow decisions. The browser remains responsible for browser actions; the AI layer should receive bounded inputs and return validated outputs.

🧠 LLM Providers

Design the provider layer so that model vendors are configurable rather than hard-coded. Your implementation may support a hosted provider, a self-hosted model, or an internal inference service.

llm_config = {
    "provider": "your-provider",
    "model": "your-model-id",
    "temperature": 0.2,
    "response_format": "json"
}

# AutoMesh should validate the provider response
# before allowing downstream automation to use it.

🛠️ AI Tool Calling

Expose a small, explicit allowlist of tools. Each tool should define an input schema, output schema, timeout and permission boundary.

tool = {
    "name": "get_page_title",
    "description": "Return the title of the current authorized page.",
    "input_schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": False
    }
}

📐 Structured AI Output

Require machine-readable output and validate it before execution. A useful pattern is to separate model output from automation commands so the model cannot directly execute arbitrary code.

{
  "action": "extract",
  "fields": ["title", "price"],
  "confidence": 0.94
}

💳 Plans & API Access

After a customer purchases a plan that includes API access, the dashboard should allow them to create, rotate and revoke API keys. Keys should be shown once at creation time where possible.

🔐 Authentication

Use an Authorization header rather than placing API keys in URLs or browser-visible source code.

Authorization: Bearer YOUR_AUTOMESH_API_KEY
Content-Type: application/json

📨 Request Format

The exact endpoint should match your production API. The following structure is a recommended documentation pattern.

{
  "workflow": "browser-extraction",
  "input": {
    "url": "https://example.com",
    "fields": ["title"]
  },
  "options": {
    "browser": "chromium",
    "timeout_seconds": 60
  }
}

📥 API Responses

Return predictable JSON with a stable status field, job identifier and machine-readable error object.

{
  "id": "job_123456",
  "status": "completed",
  "data": {
    "title": "Example Domain"
  },
  "usage": {
    "requests": 1
  }
}

⚠️ Errors, Retries & Limits

🌍 Proxy Configuration

AutoMesh should support authorized proxy routing through explicit configuration. Use proxies only where you have permission and comply with the destination service's rules and applicable law.

HTTP_PROXY=http://proxy.example:8080
HTTPS_PROXY=http://proxy.example:8080

# Optional application-level configuration
AUTOMESH_PROXY_URL=http://proxy.example:8080

For authenticated proxy credentials, use secure secret storage instead of committing credentials to source control.

🗂️ Sessions & Browser Profiles

Use separate profiles or isolated browser contexts for independent jobs. Treat session data as sensitive and define explicit retention and cleanup rules.

☁️ Remote Browser Connection

A production deployment may run browsers in separate workers or containers. The API can create a job, assign it to a browser worker, stream status events and return the final structured result.

🧩 Plugin System

Plugins should have a manifest, version, declared permissions and lifecycle hooks. Keep plugins isolated from core secrets unless access is explicitly required.

{
  "name": "example-plugin",
  "version": "1.0.0",
  "entrypoint": "plugin:run",
  "permissions": ["workflow.read"]
}

🧩 Browser Extensions

Document extension loading separately for each framework and browser. Validate extension source, version and permissions before allowing it in shared or production environments.

🔧 Custom Tools

Custom tools are best implemented as small, testable functions with strict schemas. The AI layer should request a tool; the application validates and executes it.

🌱 Environment Variables

AUTOMESH_API_KEY=replace_with_real_key
AUTOMESH_BASE_URL=https://api.your-domain.example
AUTOMESH_TIMEOUT=60
AUTOMESH_BROWSER=chromium
AUTOMESH_LOG_LEVEL=INFO

⚙️ Project Settings

Keep non-secret defaults in version-controlled configuration and keep credentials outside the repository.

🛡️ Security

• Use HTTPS for API traffic.
• Never expose API keys in frontend bundles.
• Use least-privilege scopes for keys and plugins.
• Validate all AI-generated structured data before execution.
• Log request identifiers without logging secrets.
• Define data retention and session cleanup policies.

🧑‍💻 Developer SDK Architecture

AutoMesh should expose a stable developer interface while keeping browser platforms and AI vendors behind adapters. This allows new providers to be added without changing customer workflows.

class BrowserProvider:
    def create_profile(self, config): ...
    def start_profile(self, profile_id): ...
    def connect(self, session): ...
    def stop_profile(self, profile_id): ...

⌨️ AutoMesh CLI

Add a command-line interface for local development, CI/CD and operations.

automesh login
automesh profiles list
automesh profiles start PROFILE_ID
automesh jobs run workflow.json
automesh jobs status JOB_ID
automesh providers doctor

🐳 Docker & Browser Workers

Separate the API service from browser workers. Workers can receive jobs, launch authorized sessions, execute workflows and return normalized results.

services:
  api:
    image: automesh-api
  worker:
    image: automesh-browser-worker
  queue:
    image: redis:latest

🧪 Testing & Debugging

📊 Observability

Give every AutoMesh job a correlation ID across API, queue, AI and browser events.

🌐 Browser Profile Provider Architecture

AutoMesh can integrate with multiple profile-oriented browser platforms through a common adapter layer. The goal is authorized interoperability and automation, not claiming to bypass website security or guarantee that automation cannot be detected.

🧩 AdsPower Connector

Create a dedicated AutoMesh connector around the provider's supported Local API. The connector can check connectivity, start an authorized profile and normalize returned connection details before passing control to the selected automation framework.

provider = AutoMeshProvider(
    name="adspower",
    base_url="http://local-provider-endpoint"
)

session = provider.start_profile(profile_id="PROFILE_ID")

# Normalize:
# session.debug_endpoint
# session.webdriver_path
# session.profile_id

🧩 Multilogin Connector

The AutoMesh adapter should separate provider profile lifecycle operations from Selenium, Playwright or Puppeteer automation. Provider credentials belong in secure configuration, while workflows receive a normalized session object.

session = automesh.providers.multilogin.start(
    profile_id="PROFILE_ID"
)

browser = automesh.browser.connect(session)
browser.open("https://example.com")

🧩 MoreLogin Connector

Support local and remote provider modes through configuration. AutoMesh should expose only capabilities actually enabled by the provider API and connected account.

AUTOMESH_PROVIDER=morelogin
AUTOMESH_PROVIDER_MODE=local
AUTOMESH_PROVIDER_URL=http://127.0.0.1:40000

🔌 Adding More Providers

Use a provider registry instead of hard-coding product names across the platform.

PROVIDERS = {
    "selenium": SeleniumProvider,
    "playwright": PlaywrightProvider,
    "drissionpage": DrissionPageProvider,
    "adspower": AdsPowerProvider,
    "multilogin": MultiloginProvider,
    "morelogin": MoreLoginProvider,
}

🤖 AI Automation Agents

AI agents should orchestrate approved tools rather than execute unrestricted code. Define exactly what an agent may observe and which browser, API and plugin actions it may request.

{
  "goal": "Extract approved page data",
  "state": "planning",
  "allowed_tools": [
    "browser.navigate",
    "browser.read",
    "browser.click",
    "browser.type"
  ]
}

🧠 Planner → Executor → Validator

👁️ Vision-Based Automation

Use vision models for visual reasoning when deterministic page selectors are insufficient. Keep screenshots and visual frames as explicit, permission-controlled inputs.

🔗 MCP & AI Tool Ecosystems

AutoMesh can expose approved browser and workflow capabilities as structured tools for compatible AI-agent ecosystems.

{
  "name": "automesh.browser.status",
  "description": "Return status for an authorized AutoMesh browser session",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session_id": {"type": "string"}
    },
    "required": ["session_id"]
  }
}

👤 Human Approval Gates

Add explicit confirmation for actions with significant external impact. The AI can prepare a proposed action, while AutoMesh requires approval before execution.

{
  "status": "awaiting_approval",
  "proposed_action": "submit_workflow",
  "approval_token": "approval_example"
}

🔀 Workflow Orchestration

For long-running tasks, separate submission from execution. Return a job ID immediately, process work asynchronously, and expose status retrieval or webhook notifications.

📡 Webhooks

Webhooks allow AutoMesh to notify your application when a job changes state. Sign outgoing webhook requests and verify signatures before processing them.

{
  "event": "job.completed",
  "data": {
    "id": "job_123456",
    "status": "completed"
  }
}

🚀 Production Checklist