User manual (customers) · local web app + API + optional MCP · Database MCP build & MCP tools (troubleshooting)
This document is the customer-facing manual: setup, settings, everyday use, and troubleshooting. Packaging, billing servers, and engineering internals ship with the downloadable source package; they are not published on this website.
The product is a FastAPI-based automation and skill-building workstation. It combines a browser UI, desktop helpers (screenshots, OCR, mouse/keyboard), optional Playwright browser automation (MCP relay), FastSkills-oriented skill packaging, and an optional MCP server for AI assistants.
.paddlex).The product documentation does not name a single minimum OS build for every deployment (e.g. “Windows 10 1903” or “macOS 12”). What follows reflects practical use of the ML/desktop stack together with Python and vendor requirements for your machine.
Practical minimums (all platforms)
.paddlex).uvx, upstream AI APIs unless you pre-cache artifacts).Windows
pywin32 >= 306, PyAutoGUI, pynput, and other Windows-oriented packages listed there). Project builds exclude macOS-only pyobjc on Windows.2.1.1 CPU: AVX support (Windows .exe and PaddlePaddle)
The standard Windows build (PyInstaller folder bundle with PaddleOCR / PaddlePaddle) requires a 64-bit x86-64 CPU with AVX (many prebuilt wheels effectively expect AVX2-class CPUs).
Chips that only implement SSE4.x and not AVX—such as some low-power parts (e.g. Intel Pentium Gold 4425Y)—are outside the supported hardware for that package: startup may fail with errors like missing libpaddle, NameError: libpaddle, or DLL initialization failed.
If you must install on a machine without AVX, contact the software provider or your license/support channel to request a separate, individually supplied package when available. Such builds are provided only on request; the provider offers no guarantee of performance, responsiveness, stability, or full feature parity with the standard distribution.
macOS
Linux
DISPLAY on X11/Wayland setups). Use --no-gui for headless servers when you only need HTTP.window_title): on Linux the app does not use PyGetWindow (Windows-oriented). Install xdotool (sudo apt install xdotool) so responses can include the active window title; pure Wayland sessions may still return Unknown.The matrix below lists a practical bottom line per OS column (what must be true on the host for that row to work). It is not a vendor certification—exact build numbers follow Python, Node/Playwright, Docker, and uvx documentation for your machine. Docker adds host rules from the Docker vendor (RAM, Windows WSL 2 / Hyper-V, minimum macOS / Linux kernel). If Database MCP uses Docker at runtime, those apply on top of the Skill Builder baseline. The Linux column assumes typical 64-bit glibc distributions (e.g. Debian/Ubuntu family); other distros may need extra work for ML wheels. Linux dependency lockfiles for source installs are documented in the application source package.
| Component / stack | Windows | macOS | Debian / Ubuntu (glibc Linux) |
|---|---|---|---|
| Skill Builder (core) | 64-bit 10+; practical minimum 8 GB RAM for OCR + models. Install from requirements-windows.txt (pywin32, PyAutoGUI, etc.). Desktop automation expects a normal user session. |
Python 3.10+ when using a full stack from source (pyobjc, etc.). Enable the Privacy & Security permissions listed under macOS in §2.1 (Accessibility, Input Monitoring, Screen Recording, Automation as prompted). |
64-bit glibc Linux (e.g. Debian/Ubuntu family). Optional tray/GUI needs DISPLAY (X11/Wayland). HTTP-only servers: --no-gui. |
| Playwright MCP (optional) | Node (LTS recommended); install browsers per the Playwright MCP documentation in the application source package, or use external MCP via PLAYWRIGHT_MCP_EXTERNAL_URL. |
Same prerequisites as Windows; browsers must be supported by Playwright for your macOS/CPU. See the application source package for setup details. | Same prerequisites as Windows; on minimal servers often run npx playwright install-deps once (usually sudo). Details: application source package. |
| Database MCP (optional) | Native: vendor/db_mcp_server/db-mcp-server.exe (bundled or built with Go/Docker once). Or Docker runtime: Docker Desktop must meet Docker’s current Windows + WSL 2 requirements; image pulled (§5.1). | Native: binary under vendor/db_mcp_server/ if present. Or Docker: Docker Desktop’s macOS version ceiling applies—old Macs may fail both paths (see warning below). | Native: Linux binary in vendor/ or build. Or Docker Engine + docker on PATH + pulled image (common on servers; no Desktop required). |
| Python Interpreter MCP (optional) | Default stdio: uvx on PATH (first run needs PyPI/network unless cached). Override command in python_interpreter_mcp_config.json. External: any reachable MCP base URL. |
Same pattern (uvx / custom command / external). |
Same pattern; install uv/uvx via pip or distro if missing. |
| FastSkills (required for full skill workflow) | Child process: default uvx fastskills (needs uvx + network first time) or python -m fastskills with AUTOMATION_FASTSKILLS_USE_PYTHON_MODULE=1, or AUTOMATION_FASTSKILLS_CMD_JSON. Folders my-fastskills/skills + my-fastskills/output. |
Same env-based overrides; Apple Silicon / Intel per Python wheels. | Same; ensure uvx or alternative launcher is available. |
Legend: rows are major stacks; columns are host OS families. “Optional” integrations can be disabled in their config files if you do not need them.
Avoid a “double dead-end” on old hardware (example: pre-2015 Mac notebooks):
You might install the core Python app, then discover that Database MCP has no usable native db-mcp-server binary in your bundle or build,
so you plan to rely on the Docker fallback—only to find that Docker Desktop no longer supports your macOS version (or the machine lacks RAM / virtualisation support).
Docker is not a universal escape hatch. Before counting on Database MCP, check Docker’s current host requirements for your exact OS build; on very old Macs, plan to run Database MCP on a newer host, use a pre-built native binary from a supported release channel, or leave Database MCP disabled if you only need the rest of the app.
The in-app Settings → Advanced → Capabilities report shows live status for FastSkills, Playwright MCP, Database MCP, and Python Interpreter MCP. Offline / air-gapped notes: §8.5 (FastSkills). Python Interpreter MCP (stdio, uvx, external mode): documented in the application source package.
AUTOMATION_SERVICE_HOST / AUTOMATION_SERVICE_PORT — bind address and port (default port often 8800).AUTOMATION_SKIP_OCR_WARMUP — skip eager Paddle warmup at startup if set appropriately (see app hints).AUTOMATION_CORS_ORIGINS — CORS when the web UI is served from a different origin than the API.Packaged desktop builds may use different launch flags. Operators and developers: additional environment variables (billing, recording, MCP) are documented in the application repository.
Start the product with the installed executable or launcher from your platform’s package (Windows .exe, macOS .app, or your Linux distribution’s start method). The local web UI and API listen on the configured port (often 8800 for HTTP).
Open http://127.0.0.1:8800 (or your chosen host/port) in a browser. API docs are typically at /docs and OpenAPI at /openapi.json.
By default, the full app also serves HTTPS on port 8843 (see AUTOMATION_HTTPS_PORT). To disable HTTPS, use your build’s documented launch flags or set AUTOMATION_USE_HTTPS=0 if supported. Running from a Python source checkout (python main.py / uvicorn) is documented in the application source package.
Port conflicts: If 8800 is taken (e.g. by another stack), set AUTOMATION_SERVICE_PORT or pass --port to the launcher.
The first time HTTPS is used, the app creates a self-signed certificate under a tls/ folder next to your app data root (beside the .exe on Windows; inside .app/Contents/MacOS/ on macOS; or next to the runtime root for your install). For a source checkout, paths follow the project layout — see the application source package. Files: tls/localhost.crt (public) and tls/localhost.key (private). The console prints the full paths when the cert is generated or replaced.
The certificate includes SAN entries for localhost, open-skills.local, 127.0.0.1, and ::1. If you use open-skills.local, add 127.0.0.1 open-skills.local to your hosts file. After the app regenerates the cert (e.g. to add a new name), trust the new localhost.crt again.
Chrome on macOS — remove the “Not secure” / certificate warning
localhost.crt).localhost.crt if needed, then select the certificate (e.g. “Automation Studio Local”).https://127.0.0.1:8843/docs or https://open-skills.local:8843/docs; Chrome should treat the site as trusted.Windows (brief): Import localhost.crt into Trusted Root Certification Authorities for the current user (e.g. via Certificate Manager / certmgr.msc), then fully restart Chrome.
Install only the .crt file into the trust store. Never share the .key file. Self-signed local certs are for development; do not use them for production internet-facing HTTPS.
Open Settings from the sidebar. Tabs include:
db-mcp-server (connections JSON, tools prefixed asb_db_). See §5.1 for Docker image / SQLite paths; §5.2 for how to phrase tool + SQL requests to an AI assistant.Many security-sensitive options require Save in the header and sometimes an application restart (on-screen hints apply).
When no native db-mcp-server binary is present (PyInstaller bundle or vendor/db_mcp_server/), the app can run Database MCP through Docker if the image already exists locally.
The app uses docker image inspect to detect that; it does not run docker pull for you.
1) Native db-mcp-server available (bundled next to the frozen app under _internal, or vendor/db_mcp_server/db-mcp-server(.exe) in dev)
DB_MCP_SERVER_FORCE_DOCKER=1 to ignore the vendor binary and force the Docker image instead (see the application repository documentation).2) No native binary — Docker fallback
docker must be on PATH (GUI-launched apps may not inherit Docker’s PATH; fix the environment or use a full path).DB_MCP_SERVER_RUNTIME_IMAGE (default freepeak/db-mcp-server:v1.8.0) must already be pulled: docker pull … (below).DB_MCP_SERVER_DISABLE_DOCKER=1 to turn off this fallback (only native binary will be considered).3) Neither native binary nor a pulled Docker image
asb_db_* tools). Startup logs print hints such as “no native binary and Docker fallback unavailable”.vendor/ / rebuild the .exe with the binary bundled, or leave Database MCP disabled in db_mcp_server_settings.json (enabled: false) if you do not need it.Run in a terminal:
docker pull freepeak/db-mcp-server:v1.8.0With Docker Desktop, this uses the same engine as the GUI. After a successful pull, the in-app check for the Docker fallback image should pass.
For another tag or a private image, set DB_MCP_SERVER_RUNTIME_IMAGE to match, then pull that reference, for example:
export DB_MCP_SERVER_RUNTIME_IMAGE=freepeak/db-mcp-server:v1.8.0
docker pull "$DB_MCP_SERVER_RUNTIME_IMAGE"freepeak/db-mcp-server:v1.8.0 and confirm the pull.
When Database MCP starts db-mcp-server in Docker, this application bind-mounts the parent directory of your active connections JSON
(the folder that contains db_mcp_server_config.json, or the file pointed to by AUTOMATION_DB_MCP_CONFIG_PATH) read-write at
/asb-mcp-data inside the container. In connections, set SQLite to an absolute path under that mount, for example:
"database_path": "/asb-mcp-data/db_mcp_local.sqlite"
The database file then lives on the host next to the config file. To use another host folder instead, set
DB_MCP_SERVER_DOCKER_DATA_DIR to that folder’s absolute path before starting the automation server.
The whole mounted directory is visible inside the container — only mount directories you are comfortable exposing to the db-mcp image.
If you rely on SQLite with Database MCP inside Docker, the default upstream image tag may not match your needs. Operators should read Database MCP build & troubleshooting.
With the app’s MCP endpoint connected in your client (for example streamable HTTP at http://127.0.0.1:8800/mcp-http),
you do not need to guess JSON field names for tools. Say clearly which tool to invoke and which SQL to run;
the model maps that to the tool schema (sql, query, etc.) for you.
Tool names follow the connection id in your connections JSON — for example local_sqlite yields
asb_db_query_local_sqlite, asb_db_schema_local_sqlite, and so on. Replace local_sqlite in the examples below if your id differs.
asb_db_query_local_sqlite，执行 SQL：SELECT sqlite_version();，我要看 SQLite 版本。」asb_db_query_local_sqlite 查一下当前库的 SQLite 版本。」asb_db_query_local_sqlite with SQL SELECT sqlite_version(); to show the SQLite version.”SELECT sqlite_version(); is enough for the library version string.PRAGMA compile_options; or SELECT sqlite_source_id(); via the same query tool — only if that tool allows those statements.Use POST /api/desktop/desktop_ocr_action (MCP tool id desktop_ocr_click_text when exposed). You can pass region, wait seconds before capture, target_text, mouse action, and optional offsets. On macOS, mouse execution may use pynput / Quartz before PyAutoGUI (see server implementation).
Use POST /api/host/mouse/move and POST /api/host/mouse/click for mouse automation.
The in-app Mouse Click flow records a replay script that calls /api/host/mouse/click with button and clicks (e.g. double-click = left + clicks: 2);
omit x/y to click at the cursor position when the request is handled (after any client-side countdown).
Use POST /api/host/keyboard/type, …/press, and …/hotkey for typing and key combinations.
Other desktop flows (window focus, region screenshot, launch/close app, etc.) are under /api/host/* in OpenAPI (canonical host automation prefix).
Older URLs such as /api/remote/mouse/click and /api/action/* aliases still work but are hidden from OpenAPI; new integrations should use /api/host/*.
Playwright is exposed via relay routes under /playwright/* and optional MCP tools when enabled. Configure browser mode in Settings → General → Playwright (including CDP attachment to an existing browser).
Start/stop recording from the UI; recorded HTTP sequences can be exported as Python replay scripts. MCP transport calls (/mcp/*) are generally omitted from replay — prefer direct REST calls in recordings.
Build or import skills; when FastSkills MCP is configured, tools such as listing skills and executing tools may be available through that integration.
/openapi.json; interactive Swagger — /docs. Each OpenAPI operationId maps to a candidate MCP tool when MCP is enabled./mcp, streamable HTTP /mcp-http (see server console on startup).Some HTTP routes are hidden from the MCP tool list by default (for example license administration and diagnostics), while remaining available over HTTP or Swagger if enabled. Use Settings → MCP tools to adjust visibility; changes are saved to app data and usually require a server restart (follow on-screen hints).
Technical details (built-in exclusion IDs, JSON schema, non-configurable routes) are documented in the application source repository.
If you have a subscription license, many API and automation calls count toward a monthly limit. The Usage view uses the same counting rules for graphs, with small exceptions so opening Usage does not skew its own numbers.
Exact path lists and source functions (should_count_request, etc.) are for operators — see the application source repository.
x, y; verify coordinates match primary display resolution.host.docker.internal vs 127.0.0.1).Authorization: Bearer <secret>:
POST /api/run_code, /playwright/*, and /fastskills/*.
Other APIs (including /api/host/* and legacy /api/remote/* / /api/action/* aliases) do not use this middleware — do not assume the key gates the whole server.
AUTOMATION_CORS_ORIGINS or browser entry settings if the UI is served from a different origin than the API.
By default the app starts FastSkills with uvx fastskills, which may download packages from the network (PyPI).
If you see TLS errors, timeouts, or “connection reset” during startup or first use, the machine may be offline, behind a strict proxy, or blocked from PyPI.
uvx / pip / TLS / handshake failures; skill list or MCP tools hang or fail.pip install fastskills into the Python environment that launches this application. Then set
AUTOMATION_FASTSKILLS_USE_PYTHON_MODULE=1 (values 1, true, yes, on are accepted). The app will start python -m fastskills with your configured skills and work directories.AUTOMATION_FASTSKILLS_CMD_JSON to a JSON array of strings, e.g.
["/opt/venv/bin/python","-m","fastskills","--skills-dir","/abs/path/to/skills","--workdir","/abs/path/to/output"].
Use absolute paths if the working directory differs. Invalid JSON is ignored with a log warning; fix the variable and restart..exe). Ensure that folder exists and contains your skill packages.uvx, env flags, paths).Monthly quota and the Usage tab both skip diagnostics-style paths (capabilities, machine ID, license endpoints, etc.). See the application source repository for the full list.