Veilus

Add rows to a dataset, in the same shape as create_dataset's `rows`. Bad rows are reported in `rejected` by row number and do not block good ones.

Assign a dataset to existing profiles. A fixed dataset goes to each profile's Identity slot and gives it one unassigned row (lowest index first); profiles left without a row are named in `withoutRow` and get nothing — never share one account between profiles. A consume dataset goes to the Content slot. Refuses the whole call if a profile already has a different dataset in that slot, unless force: true; refuses column names that also exist in the dataset in the profile's other slot. Every later run of an APPROVED script on those profiles carries the data; schedules and run_batch need no new field.

Assign a proxy pool to existing profiles, one slot each. Refuses the whole call (nothing assigned) if any profile already has a proxy or pool, listing them; pass force: true to replace. Does NOT change the profiles' timezone: if the new proxy is in another country, launch_profile will be blocked by the geo check. New profiles should get their pool through create_profiles instead.

Click an element of a running profile's page by node_id with a real mouse: the pointer moves to a point inside the element, then presses and releases. Fails if the page changed since the snapshot (take a new one), if the element has no visible box (hidden or zero-size — click its visible label or parent), or if another element covers it (the error names it — close or scroll past it first). A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

Compile a drag-and-drop DSL script into runnable code. Does not run it. Agents writing scripts should use save_script instead.

Create a dataset: a table stored in Veilus that approved scripts read per profile. mode `fixed`: each profile gets ONE row for good (accounts); its columns arrive as process.env.VEILUS_VAR_<COLUMN>. mode `consume`: each run takes `rows_per_run` (1-50, default 1) unused rows; a failed run gives them back, a successful run marks them used; they arrive as VEILUS_VAR_ROWS (JSON array of {COLUMN: value}) and, when rows_per_run is 1, also one variable per column. VEILUS_VAR_ROW_INDEX is the row's number. Columns are UPPER_SNAKE_CASE; ROWS, ROW_INDEX, PROFILE_ID, RUN_ID and DEBUG_PORT are reserved. Mark a column `secret: true` for passwords: it is stored and given to approved scripts, but no tool ever returns it. Bad rows are reported in `rejected` by row number (from 1). Returns `datasetId`.

Create 1 to 50 new browser profiles in one call. With proxy_pool_id (a static pool, e.g. from import_proxies), each new profile gets the pool's least-loaded slot (free slots first, lowest index on ties) and its timezone and language are generated to match that slot's exit-IP geo; a profile whose slot has no known geo is listed in `failed` and NOT created. Without proxy_pool_id the fingerprint is random. The whole call is rejected, creating nothing, if it would exceed the plan's profile limit. `name_template` replaces {n} with 1, 2, ...; `tags` are tag names. `failed[].index` is that same n. With identity_dataset_id (a fixed dataset) each new profile takes one unassigned row, and the call is refused if count exceeds the unassigned rows; content_dataset_id (a consume dataset) goes to every new profile's Content slot.

Create a schedule that runs an APPROVED script on the given profiles at set times. The script must already be approved by the user in Veilus → Flow: an unapproved script is refused now, not skipped later. schedule_type: interval (interval_minutes, with interval_unit minutes or seconds, at least 5 seconds), daily (daily_hour and daily_minute, the computer's local time), weekly (daily_hour, daily_minute and weekly_day, 0 = Sunday), cron (cron_expr, 5 fields) or once (run_at, a future RFC 3339 time with offset; the schedule runs once and then turns itself off). concurrency (default 1, 1-16) and stagger_ms (default 0, 0-600000 i.e. 10 minutes) apply to every run. Returns the schedule, including nextRunAt.

Run a JavaScript expression in a running profile's page and return its value as `text`, JSON-encoded (strings come back quoted); promises are awaited. `undefined` comes back as the text `(undefined)`, not JSON `null`. A thrown error comes back as text starting with [JS Error] — this is a normal call result, not a tool failure. Results over 64 KiB are cut and flagged truncated: true. A synchronous loop is stopped by the PAGE ITSELF after about 9 s; its result also comes back as ordinary [JS Error] text. A promise that never settles instead makes the call itself fail after 10 s with a timeout error. This is NOT a sandbox: it runs with the full rights of the logged-in page (reads cookies, sends requests as the user). A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

How many browsers are open (active), waiting for a slot (queued) and allowed at once (max) on this machine. Use it to choose run_batch concurrency.

Read a dataset's rows in order: `limit` rows (default 100, at most 500) from `offset`. Each row has its index, its values, and for a fixed dataset the profile it is assigned to, for a consume dataset its state. Secret columns are always left out of `values`.

Show which proxy a profile goes out through: its pool and slot, the slot's host:port, whether it needs auth, and the slot's detected country and timezone. Never returns the password.

Result of a run by `run_id` — use after calling run_script.

Read the source and approval state of a Raw script, to fix it and save_script it again. Returns `scriptId`, `name`, `description`, `version`, `source`, `approved` and `origin`.

Create a static proxy pool from proxy lines (host:port, host:port:user:pass or user:pass@host:port). Prefix a line with socks5:// for a SOCKS5 proxy; http:// or no prefix means HTTP; https:// is rejected (TLS to the proxy is not supported). Bad lines are reported in `rejected` by line number (counting from 1) and do not block good ones; if no line is valid, nothing is created. Returns pool_id for create_profiles or assign_proxy_pool. Passwords are stored but never returned.

Launch a profile: waits for its browser to finish starting, then returns `{pid, cdpUrl}`. `cdpUrl` (http://127.0.0.1:<port>) is the profile's own Chromium DevTools endpoint: any CDP client — Playwright `connectOverCDP`, Puppeteer `connect`, browser-use, playwright-mcp — can drive the profile through it with its fingerprint and proxy. It has no authentication: any local process can use it while the profile runs. If the profile pool is already full this fails immediately with a 409 (`REST returned 409 ...`) rather than queuing. With `diagnostic: true` it opens the profile without its fingerprint, to tell whether a site blocks the fingerprint or the proxy.

List datasets: id, name, mode, columns with their secret flag, rowsPerRun, row counts (total and assigned for fixed; available, reserved and used for consume) and how many profiles use each. Never returns row values.

List Veilus browser profiles, with their running state. A running profile also carries `cdpUrl` (see launch_profile).

List proxy pools: `pool_id`, `name`, `kind` (static or rotating), `entry_count` and `countries` detected for their exit IPs. Never returns credentials.

List the most recent runs, newest first: status and profile counts, without per-profile detail (get_run_result has that). Without schedule_id it lists runs of every schedule and of run_script and run_batch. limit defaults to 20, at most 100.

List every schedule: its script, target profiles, timing, enabled flag, and next and last run times.

List every script, newest first, without its source: `scriptId`, `name`, `description`, `version`, `mode` (`raw` or `dsl`), `origin` (`mcp` if an agent wrote it, `app` if the user did), `approved` and `updatedAt`. Check here before save_script so you update an existing script instead of saving a duplicate.

Load a URL in the tab of a RUNNING profile and wait for its load event (up to 15 s); on timeout it PROCEEDS ANYWAY and the result says the page is still loading - then call wait_for_element for what you need before reading the page. The profile must already be open - call launch_profile first; this never opens it.

Press one named key in a running profile's page: Enter, Tab, Escape, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, Delete or Space. If no input is focused, the LAST input on the page is focused first. For text use `type`. A JavaScript alert/confirm/prompt that the action opens is answered at once: `dialog` "dismiss" (default, i.e. Cancel) or "accept" (OK), with `prompt_text` as the typed answer to a prompt; the result says which dialog opened and how it was answered.

For a consume dataset: put every used row back to available, so runs take them again. Returns how many rows changed.

Run an APPROVED script on many profiles for real. Returns the run IMMEDIATELY; its `id` is the run_id for get_run_result. Unlike run_script (a trial on at most 3 profiles, no approval needed), the script must have been approved by the user in Veilus → Flow, otherwise the call is refused. A profile id that does not exist is counted as a failed profile of the run, not rejected (unlike create_schedule, which refuses unknown ids with 404). concurrency (default 3, 1-16, capped by get_capacity's `max`) is how many profiles run at once; stagger_ms (default 1500, 0-600000 i.e. 10 minutes) is the pause between launches; use get_capacity to choose.

Run a schedule once right now, without waiting for its timer. Returns the run IMMEDIATELY; its `id` is the run_id for get_run_result. Refused while the schedule already has a run in progress, or if its script is not approved.

Run a script on the given profiles. Returns the run IMMEDIATELY, without waiting for it to finish; its `id` is the run_id for get_run_result.

Save a Playwright (TypeScript) script into Veilus Flow. Without script_id: create a new script; with script_id: replace its source. Contract - violations are rejected with line numbers: (1) connect with chromium.connectOverCDP(`http://127.0.0.1:${process.env.VEILUS_DEBUG_PORT}`); (2) no chromium.launch/launchPersistentContext; (3) use browser.contexts()[0], not newContext(); (4) no setUserAgent/setViewportSize - identity belongs to the profile; (5) errors must exit non-zero: main().catch((e) => { console.error(e); process.exit(1); }); (6) import only playwright and Node built-ins; (7) end main() with `await browser.close()` - it only disconnects from the profile's browser and lets the script exit; without it the run hangs. Read variables via process.env.VEILUS_VAR_<NAME> (names are UPPER_SNAKE_CASE); print what you need to see with console.log to stdout. A newly saved script is not approved: run_script can run it (on at most 3 profiles), schedules wait until the user approves it in the app. `name` is used only when creating; updating (with script_id) does not rename, and only scripts saved by an agent can be updated. Returns `scriptId` (this script's id — pass as script_id to get_script or to save_script again), `version` and `approved`.

Scroll a running profile's page by `amount` pixels (1 to 20000) in direction up, down, left or right, with mouse-wheel steps at the pointer's position. Like a real wheel, a scrollable area under the pointer scrolls instead of the page — after a click inside such an area, scroll there, or click outside it first. On a macOS profile the distance varies a few percent around `amount`, like a real wheel; the result reports the pixels actually scrolled.

Attach a file to a file input (<input type=file>, often shown as a "Choose File" button) of a running profile's page by node_id, instead of clicking it - a click opens the system file picker, which cannot be controlled. Only files inside the app's uploads folder (~/.veilus/data/uploads) are allowed: pass the file name, or an absolute path inside that folder; anything else is refused. Ask the user to copy the file there first.

Replace ALL stored variables of one profile with `variables` - not a merge: names you omit are deleted, {} clears them. Names are UPPER_SNAKE_CASE, at most 64 variables, values up to 32 KiB. They are delivered only to runs of APPROVED scripts (run_batch, schedules, and run_script once the user has approved the script) as process.env.VEILUS_VAR_<NAME>; a run_script trial of an unapproved script gets only the variables passed to that call. A variable passed to the run itself wins on the same name. Returns the stored names, never the values.

Turn a schedule on or off. Turning it on recomputes the next run from now and requires its script to still be approved; turning it off keeps the schedule and its run history.

Accessibility snapshot of the current page of a running profile: one line per element with role, name and [id=N]; pass N as node_id to click or type. Ids change when the page changes - take a new snapshot after navigating or clicking. Lists at most 150 elements and 64 KiB; truncated: true means the page has more - use wait_for_element with a CSS selector to reach an element that is not listed. Elements inside same-origin iframes follow a `--- iframe URL ---` line and work with click and type like any other; a cross-origin iframe gets a `(cross-origin …)` line with its URL but its elements are not listed - navigate to that URL to work inside it.

Stop a profile's browser and release everything its launch held. Stopping a profile that is not running also succeeds. Returns an empty result.

Test every proxy in a pool now: alive or dead, latency, exit IP and its country and timezone. Refreshes the pool's cached geo, which create_profiles uses. A dead proxy can take up to about 10 seconds.

Focus an element by node_id and type text into it, one key event per character (at most 5000 characters). Replaces the field's current content: existing text is removed before typing. If the result notes that the value could not be confirmed (masked, length-limited or auto-formatted fields), verify the field with snapshot or evaluate_js.

Remove a dataset from profiles. For a fixed dataset their rows become unassigned again. Profile ids that no longer exist are accepted, so rows held by deleted profiles can be freed.

Wait until a CSS selector matches an element in a running profile's page (polls every 200 ms; timeout_ms 1 to 30000, default 5000) and return its node_id for click or type. Use after navigate or click to wait for the next page.