Figranium：可视化搭建浏览器自动化并作为 API 运行

What You Get

• Block‑based automation — build flows with actions like click, type, wait, hover, and execute JavaScript against modern pages.
• Task API — trigger saved tasks via HTTP API, pass variables at runtime, and secure runs with the API key you control.
• Executions & Cabinets — inspect results, screenshots, and recordings in Executions; route browser downloads into task-selected Cabinets for later download or upload.
• Proxy management — host, rotate, or import HTTP/SOCKS proxies, flag a default, and toggle rotation per task.
• Embedded Templates — browse, preview, and import community workflows directly from the Dashboard or task-creation menu.
• Task Scheduling — run workflows automatically using visual interval/daily/weekly/monthly settings or advanced cron expressions.
• Reliable execution — track queued and running tasks, cancel queued executions, and retrieve complete results beyond bounded history previews.
• Security-first — session authentication, IP allowlists, secret management, and audit trails live entirely inside your environment.

Official Partners

Figranium is proudly supported by:

Featured Partners

Thordata — Premium residential proxy infrastructure for reliable web scraping and browser automation.

RapidProxy — 90M+ residential IPs built for browser automation and web scraping, with smart rotation and stable sessions. From $0.55/GB with non-expiring traffic. Use RAPID10 for 10% off.

Integration Partner

SimplyNode — Residential proxies for web scraping and browser automation, with flexible targeting and reliable rotation.

Infrastructure Backers

Getting Started

This starts the app on http://localhost:11345 and the VNC viewer on http://localhost:54311.

Docker Compose (Standard)

1. Create a Project Directory

Create a directory for your Figranium installation and navigate into it:

mkdir figranium-server
cd figranium-server

2. Create docker-compose.yml

Create a docker-compose.yml file in your project directory:

wget https://raw.githubusercontent.com/figranium/figranium/main/docker-compose.deploy.yml -O docker-compose.yml

3. Start with Docker Compose

Run the following command to start the application in detached mode:

docker compose up -d

Reverse Proxy Deployments

Proxy only the main application port (11345). The embedded browser viewer connects through the application’s authenticated /websockify endpoint, so it does not need a separate public VNC/noVNC port.

For Caddy running on the same VM, a standard reverse proxy is sufficient:

figranium.example.com {
    reverse_proxy 127.0.0.1:11345
}

Caddy forwards WebSocket upgrades automatically. The viewer receives a short-lived, single-use ticket bound to the signed-in session, so it continues to connect safely if the proxy changes the upstream Host header. TRUST_PROXY is not required for the embedded browser viewer; enable it only when the application needs to rely on forwarded client address or protocol headers for other deployment behavior.

Session Secret

Figranium automatically generates a cryptographically random session secret on first startup and stores it in the persistent data directory (session_secret.txt). Subsequent starts reuse the saved secret. You can optionally set SESSION_SECRET to provide your own; keep the data directory persistent so existing sessions remain valid.

Configuration

Upgrading to 0.21.1

At-rest encryption in the shared secret store is now opt-in. Without MASTER_KEY, new file-backed secret writes use plaintext JSON; configure MASTER_KEY to keep them encrypted. Existing encrypted files are decrypted and migrated only when their original key is available. Preserve data/master.key (or the configured legacy MASTER_KEY_FILE) until migration is complete; missing keys never trigger destructive resets. Named API keys remain salted and hashed, not stored as plaintext. Separate 1Password password-cache encryption settings remain independent of MASTER_KEY.

| MAX_EXECUTION_QUEUE | Maximum waiting executions before new work receives 503. | 50 | | EXECUTION_QUEUE_TIMEOUT_MS | Maximum time an execution may wait for capacity. | 600000 | | EXECUTION_TIMEOUT_MS | Maximum non-headful execution runtime. | 900000 | | RESOURCE_MEMORY_RESERVE_MB | Minimum memory headroom reserved for the host. | max(512 MB, 15%) | | RESOURCE_CPU_THRESHOLD | Normalized CPU load that pauses dequeuing. | 0.9 | | RESOURCE_PROBE_INTERVAL_MS | Runtime resource-protection sampling interval. CAPTCHA capacity is detected at startup. | 30000 |

CAPTCHA solving

Figranium uses Fiptcha for CAPTCHA solving. Fiptcha owns the CAPTCHA solver implementation and its configuration, supported providers, local/remote solving behavior, model setup, and platform-specific companion tooling. See the Fiptcha repository for the current CAPTCHA documentation instead of relying on duplicated configuration here.

Proxy rotation also respects data/proxies.json (see below), and data/allowed_ips.json works as an alternate allowlist format.

Advanced Configuration

• PLAYWRIGHT_BROWSERS_PATH (or set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH) when using a shared Playwright installation.
• NODE_ENV=production enables the bundled dist/ client and reduces console verbosity.
• HOST=0.0.0.0 allows binding beyond localhost inside Docker containers, while PORT overrides the Express listen port (defaults to 11345).
• Set LOG_LEVEL to debug if you need more Playwright or proxy diagnostics.

Task Modes

Figranium has two task modes:

• Agent Mode — deterministic browser automation built from an ordered sequence of actions, control flow, variables, and extraction.
• Scrape Mode — lightweight HTTP-based scraping and extraction without launching a browser.

Visible browser sessions are a debugging/runtime capability, not a third task mode.

UI Walkthrough

• Dashboard — view metrics, search and sort Tasks, explore featured Templates, and create Tasks from scratch or a Template.
• Templates — browse the embedded community catalog, search and filter ready-made workflows, preview their details and expected output, and import them into your workspace.
• Task Editor — build Agent or Scrape Tasks, configure actions and extraction, test blocks, manage variables, choose a Cabinet, schedule runs, add resizable canvas notes, and trigger executions.
• Executions — browse queued, running, and completed runs; inspect outcomes, complete results, screenshots, and recordings; and cancel queued executions.
• Cabinets — manage durable file queues used by Task downloads and Upload blocks, including files, ZIPs, folders, and upload status.
• Settings — manage API Keys, User Agent, Proxies, Appearance, and Advanced settings, including retention, account controls, and resource information.

Task Capabilities

• Tasks support actions including navigation, click, type, wait, press, scroll, JavaScript, hover, screenshots, conditions, loops, variables, uploads, and error handling.
• Variable templating ({$var}) and structured conditions make Tasks reusable with runtime inputs.
• Extraction can return structured data from browser or scrape executions.
• See AGENT_SPEC.md for the Task schema and action contract.

Proxies

Proxies can be defined via the UI or data/proxies.json:

[
  "http://user:pass@proxy1.example.com:8000",
  { "server": "socks5://proxy2.example.com:1080", "label": "data center" }
]

• host is always available and represents your machine’s default IP.
• Rotation settings (round-robin or random) live in Settings and persist through the backend endpoints.
• Import/export operations live behind /api/settings/proxies/import.

API Surface

Figranium exposes a REST API for workflow tools, applications, and custom integrations. All endpoints are hosted on your Figranium instance, typically on port 11345.

Authentication: If enabled, provide the x-api-key header or Authorization: Bearer <key>. For internal network use, this may be optional depending on your settings.

Task Management API

• GET /api/tasks: List all saved Tasks.
• POST /api/tasks: Create a new Task.
• PUT /api/tasks/:id: Update an existing Task.
• POST /api/tasks/:id/api: Execute a predefined Task. Pass {"variables": {}} in the body to override execution variables dynamically.

Scheduling API

• GET /api/schedules: List all scheduled Tasks and their status.
• POST /api/schedules/:taskId: Create or update a schedule (supports visual config or raw cron).
• DELETE /api/schedules/:taskId: Disable/remove a schedule.
• GET /api/schedules/status/all: Get an overview of all active scheduled jobs.

Execution API

• GET /api/executions: Retrieve paginated history of past runs.
• GET /api/executions/:id: View the steps, result data, and configuration state of a specific run.

Templates API

• GET /api/templates: Browse the community Templates catalog with search, category, sort, and pagination.
• GET /api/templates/:id: Retrieve an individual Template for preview or import. These endpoints require an authenticated workspace session.

Cabinets API

• GET /api/cabinets: List Cabinets.
• Cabinet routes under /api/cabinets manage file queues, items, downloads, upload state, ZIP creation, and extraction.

Task Scripting Tips

• Use JavaScript blocks when you need custom browser-side logic:

  return document.querySelectorAll('article').length;

• Keep selectors narrow and use the selector picker to generate deterministic candidates.
• Set Task variables through the API to reuse generic workflows across multiple inputs or domains.

Workflow Recipe

1. Design a Task in the editor and add the actions required for the workflow.
2. Use conditions, loops, variables, and JavaScript where deterministic control flow needs them.
3. Add extraction or screenshot actions when you need structured output or visual evidence.
4. Configure proxy rotation when the workflow needs a different egress strategy.
5. Use the Schedule tab for automated runs, or trigger the Task through its API endpoint.
6. Pass runtime variables such as {"variables":{"query":"books"}} when calling the Task from another tool.

Task Scheduling

Figranium includes a built-in scheduler that handles automated Task execution without requiring external cron jobs or triggers.

• Visual Mode: Configure periodic, hourly, daily, weekly, or monthly runs.
• Advanced Mode: Use standard 5-field cron expressions (* * * * *) for complex schedules.
• Persistence: Schedules are stored with Task metadata and persist across server restarts.
• Monitoring: Next-run and previous-run information is available from the Task scheduling interface and execution history.

Testing & Validation

• Run npm run build before packaging for production; the dist/ folder contains the compiled assets.
• Backend logging writes to the console for debugging proxies, authentication, or browser failures.
• Use the repository's test and qualification scripts when changing execution-critical behavior.

Troubleshooting

• “Session expired” in the UI: confirm SESSION_SECRET is consistent and cookies aren’t blocked by your browser.
• Proxy import fails: inspect data/proxies.json for valid URLs; the backend validates proxy configuration before use.
• API key lost: open Settings → API Keys to view or regenerate API credentials.

Data Lifecycle

• Screenshots and recordings are accessible through Executions, not a separate Captures page.
• Large execution results are persisted separately from bounded history previews and retrieved on demand; retention cleanup also removes their stored payloads.
• Browser downloads are stored in Cabinets. Tasks can select a Cabinet, and Upload blocks can consume queued Cabinet items.
• Browser state can persist between executions; enable a Task's stateless execution option when a run should start without persisted cookies or local storage.
• Proxy lists, user-agent preferences, and other server settings persist under data/; back up that directory when those settings matter to your deployment.

Maintenance

• The project is governed by the GNU General Public License v3.0, which grants rights for distribution and modification as per the GPLv3 terms.
• Keep data/ backed up if you rely on persistent settings or browser state.
• Release updates: Docker installations should run docker compose pull followed by docker compose up -d; source installations should pull figranium/figranium and follow the project setup commands.
• Contributions: follow .github/ templates, respect CONTRIBUTING.md, and run available lint/test scripts if you touch critical areas.

Roadmap

• Settings shortcuts — dedicated API Keys, User Agent, Proxies, and Appearance sections let operators tune core settings without leaving the UI.
• Unified execution history — review results, screenshots, and recordings through Executions rather than a duplicate Captures page.
• IP rotation tooling — import proxies and automatically rotate them.
• API key workflow — manage API access without extra setup.
• Scoped API keys — support multiple individually revocable API keys with explicit permissions.
• Password manager & credential injector — securely store credentials and inject them into browser Tasks at runtime.
• Task proxy rotation toggle — enable rotation per Task execution.
• Spatial editor transition — spatial block-based Task editor.
• Action key combos — add modifier shortcuts for browser interactions.
• Click-and-drag block — add drag gesture automation.
• Recording controls — disable automated recording per Task.
• File downloads — download files from target pages and surface them through Cabinets.
• Cabinet-backed file workspace — route downloads into shared Cabinets and consume them from Upload blocks.
• Stateless mode — start Task runs without persisted cookies or local storage.
• Adblocking filters — optional ad/malware filtering for execution contexts.
• Extraction response mode — choose between HTML+data and data-only API responses.
• Folder organization — organize Tasks and assets into named folders.
• Configurable capture and execution retention — set retention in Advanced Settings, with automatic cleanup.
• Workspace templates — reusable workspace presets.
• Geo-targeted exits — choose proxy regions for Tasks.
• Complete anti-detection coverage — anti-detection controls across browser executions.
• Session recording redaction — redact sensitive fields from recordings and logs.
• Two-factor authentication — optional TOTP/second-factor support.
• Automatic self-healing selectors — recover broken locators after page changes.
• Multilingual task pages with translate.js — optionally translate browser-rendered pages before actions and extraction.
• AI-assisted fixing — suggest fixes after failed runs for user approval.
• Companion app — lightweight notifications for important execution events.
• Community presets hub — publish and discover reusable automation presets.
• Embedded Templates for instant usage — browse, preview, and import ready-made Templates directly in the Figranium UI.
• Database Tab / Local CRM — built-in interface for extracted data.
• iframe interaction support — target and interact with elements inside iframes.
• Autosave — automatically persist Task changes and editor state.
• Highlight tool — highlight elements while building workflows.
• Cron triggers — schedule Tasks with cron expressions.
• Resizable canvas notes — add and resize annotations alongside workflows.
• Page triggers — trigger a Task when a page changes in a specified way.
• Task-dedicated browser state & cookie buckets — isolate or intentionally share persistent browser state between Tasks.

Security Considerations

• Never commit your SESSION_SECRET or API keys into shared repositories.
• Use ALLOWED_IPS/data/allowed_ips.json to gate the UI when deploying to a network-exposed host.
• Rotate API keys periodically via Settings, and use Executions to review automation runs.
• Keep dependencies and the deployment environment up to date.

Community

• Report issues or request features via the GitHub repo issue tracker.
• Follow the authors on https://github.com/figranium for releases.
• Share automation recipes with other self-hosted users in your org, but respect the license for sharing infrastructure.
• Join the community on Discord.

Support the Project

If you find this project helpful, please consider supporting its development. Your contributions help keep the project maintained and the lights on!

Other ways to help:

• Star the repository to help others find it.
• Share the project with your network.
• Contribute to the code or documentation.