For developers

A script that opens a plain Chromium starts from the machine it runs on: its screen, its fonts, its graphics string, its clock.

An ARMANOS profile carries the device with it, on one of five templates, and the values are substituted inside the engine rather than painted over the page.

A user data directory divides cookies and cannot do that.

The usual answers are an incognito window, a fingerprint extension, or a virtual machine per account.

Each stops at a different place, and the one that stops nowhere costs a laptop of memory per identity.

Switch on Enable local API under For developers in the left column. The server binds to loopback and to nothing else, and it stays off until you switch it on.

On first run the app writes an access token of 24 random bytes next to its data, readable by your account alone.

Loopback is not a boundary on its own, because the pages a person visits run on this machine too. A request carrying an Origin header, a foreign Host, or a Sec-Fetch-Site other than none gets 403.

That check runs before the status route, which names the product and its exact version.

A start goes through the same path as the button in the window, and one run can skip the window without touching the profile's own Run without a window (for automation) tick box.

On ARMANOS Browser the answer is a debugging endpoint that belongs to that profile alone. Chromium takes a free port on loopback and writes it into the profile's directory, and the app hands you that address if it could read it within 4.5 seconds.

Opening a debugging port normally sets navigator.webdriver to true, which announces automation on the first line of most checks. Here it stays false, and a stand reads the value from a real page in the real engine.

On the built-in Electron engine one debugging port serves the whole app, so the answer returns ws as null.

1. 1

   Turn the local API on

   For developers in the left column, the Enable local API switch. The Access token is on the same screen.

2. 2

   Ask for the profile

   A start request with the profile id and the token.

3. 3

   Read the ws address

   The port and path of this profile and no other, when the engine wrote them within 4.5 seconds.

4. 4

   Attach and work

   Fingerprint, cookies, extensions and proxy are already in place.

Ask the local API to start the profile, take the ws address from the answer, and hand it to puppeteer.connect or to Playwright as connect_over_cdp.

Both clients enable the Runtime and Page domains when they attach, and Chromium then installs hooks a page script can notice. That is a property of the client, not of ARMANOS Browser.

Our own runner does not enable the Runtime domain. During a run it enables the Page domain on the run's tabs, to answer a page's alert or confirm, and the Network domain from the first request-wait step, and readiness is polled through document.readyState.

The Flows screen in the app has nineteen kinds of step, with repeat, branch and list loop nested up to four levels deep. Navigation is limited to http, https and about:blank, checked when a flow is saved and when it runs.

A Node client and a Python client ship in the repository, the Python one on the standard library alone.

They wrap the server API and add no logic of their own, because a client that knows more than the server starts to lie within a month.

Every error carries the HTTP status and a typed code, so a lost connection and a rejected key are told apart. Both clients verify a webhook signature and refuse anything older than 300 seconds.

The MCP server is a single Node file with no dependencies, started by your client rather than by the app. It speaks JSON-RPC 2.0 over stdin and stdout, and two environment variables point it at the API.

Ten tools, each mapped to one route the local API really implements.

• get_status

  Reachable, and the app version.

• list_profiles

  Every profile or one filtered page, without notes.

• get_active_profiles

  The ids open right now.

• launch_profile

  Opens a profile, returns its debug port.

• stop_profile

  Closes every window of a profile.

• create_profile

  Creates a profile with group and proxy.

• update_profile

  Changes only the fields you send, fingerprint values set by hand, the site login and the 2FA key included, without notes in the answer.

• delete_profile

  Moves a profile to the bin.

• get_one_time_code

  The current two-factor code.

• list_proxies

  The proxy library, without passwords.

A key is a door into the account without a password, so the secret is shown once and the server keeps only a hash and a ten-character prefix.

Rights are checked per endpoint and the default is closed. An endpoint that declares no right is unreachable with a key at all, and 18 endpoints are open to keys today.

Keys belong to the paid plans, and the plan is read on every request. Webhooks go the other way and are managed only by a person logged in with a password.

The thirteen events cover the life of a profile, the shared proxy library, keys, the team and the plan.

Each delivery carries the event, the timestamp and a signature over the timestamp, a dot and the body you received. Fields that look like a code, token, secret, password or hash never leave.

Sending is defensive: ten seconds per attempt, three attempts, no redirects, and a retry only on 5xx and 429. Fifteen consecutive failures switch the subscription off with the reason written down.

One ceiling covers the whole server API: 300 requests per 60 seconds, with the sign-in surface tighter at thirty a minute.

There is no per-plan rate limit. Your plan decides how many profiles, devices and seats you get, not how fast you may call.

The reference is generated from the same controllers that serve the requests, so it cannot promise a route that does not exist. The note about rights on each endpoint is read from the annotation in the code.