Connect a script or an AI assistant

This screen lets a program on your computer drive ARMANOS: list, open and close profiles, create them and run flows. It stays off until you switch it on, and if you do not write scripts or connect an AI assistant, you do not need it. The path is For developers in the left column, then Enable local API.

Who needs this screen

It is for people who write scripts or connect an AI assistant to the browser. The screen is titled Local automation API, and under the title the program says the same in plain words.

Leaving it off takes nothing away: profiles, proxies and flows work the same from the window. When the program starts with it off, it runs no API server and opens no shared debugging port.

Switching the API on

The choice is remembered, so the API starts with the program until you switch it off again.

1
Open For developers
The item under Automation in the left column.
2
Turn on Enable local API
The switch at the top of the card.
3
Wait for Running
The status to the right of the switch.
4
Copy the address and the token
Copy next to API address and next to Access token.

When the usual port is taken

Another program may hold the port the API normally uses. The API then takes a free one and the screen names both, so update the address in your scripts. The MCP server looks up the new port by itself.

Address and token

The API answers on this computer alone and turns away requests that come from a web page. A script sends the token with its requests, as the token parameter in the address or the x-api-token header.

Regenerate token issues a new token after you confirm. Scripts holding the old one stop working until you give them the new one.

What a script can do

The list What you can call names each request with a line on what it does. A script can list profiles and see which are running, open and close them, create one, change one and move one to the recycle bin.

It can also read the proxy library without passwords, read the current two-factor code of a profile that stores a key, list your flows and run one on chosen profiles. Opening, creating and changing a profile pass the same checks as the buttons in the window.

Creating a profile also takes a geolocation field for its location and a webrtc field for its WebRTC mode.

On the ARMANOS Browser engine, the answer to opening a profile carries a debugging address for that profile alone. Automation libraries attach to that address. On the built-in engine a script attaches through the shared debugging port, which opens only when the program starts, so after the API is switched on mid-session the screen asks you to restart ARMANOS.

A profile with a password

A closed profile answers profile_password_required until it is opened. Send the password in the body of browser/start, or open the profile first with profile/unlock; keepUntilExit keeps it open until ARMANOS closes.

A password in the address is refused with password_in_query and costs no attempt. Three wrong passwords in a row close the profile for an hour: profile_password_wrong carries attemptsLeft, profile_password_blocked carries until.

flow/run starts the open profiles and lists the closed ones in data.refused. The MCP tool launch_profile takes the password too.

POST /api/v1/browser/start: {"profileId": "…", "password": "…"}
POST /api/v1/profile/unlock: {"profileId": "…", "password": "…", "keepUntilExit": true}
POST /api/v1/profile/lock: {"profileId": "…"}
POST /api/v1/profile/password: {"profileId": "…", "password": "…", "currentPassword": "…"}
POST /api/v1/profile/password/remove: {"profileId": "…", "currentPassword": "…"}

Changing a password needs the current one, even with the token. A reset without the old password asks for your account password, so it is not in the local API.

The MCP server

MCP is the way an AI assistant such as Claude Desktop calls outside tools. The MCP server section connects it to ARMANOS through the same local API, so MCP status reads Ready once the API is running.

Through it the assistant can list profiles and see which are running, open, close, create and change them, move one to the recycle bin, read the proxy library without passwords and read a profile's two-factor code. Under What the assistant can do the screen lists these tools, one line each.

The pasted block keeps working after ARMANOS restarts, while the address and the token stay the same.

1
Switch on the local API
MCP status then reads Ready.
2
Press Copy config
The button on the Client configuration block.
3
Paste it into the assistant
In Claude Desktop: Settings, then Developer, then Edit Config.
4
Save and restart the assistant
It starts the server itself from the path under Server script.

The token and the keys in the Dashboard

The access token on this screen has no separate rights: whoever holds it can do everything listed above, two-factor codes included. Keep it the way you keep a password.

Keys with chosen rights are a different thing. They are issued on a paid plan under API keys in your Dashboard on the site, and they work with your account on our server rather than with this computer.

What this does not do

It does not take calls from other computers. The API answers on this machine alone.
It does not split the token into rights. One token opens everything on the list.
It does not hand out proxy passwords. The proxy list comes without them.
It does not run flows through the MCP server. The assistant works with profiles, while flows start from a script or from the window.
It does not install Node.js. The MCP server needs it on this computer, and the assistant starts the server itself.

Where this is decided

Each line below names the stand that checks it.

A web page is refused even with the token, and a script without the token is refused too: apps/desktop/test/local-api-gate.js
With the local API off at start, no shared debugging port is opened on either engine: apps/desktop/test/cdp-port-only-when-needed.js
The example request from the screen runs in sh and in PowerShell, the MCP lines on the screen match the server's tools, and the reason the API did not start and the restart note show on the screen: apps/desktop/test/движок-и-api-говорят-правду.js
The path under Server script stays the same after the program restarts: apps/desktop/test/путь-mcp-переживает-перезапуск.js
A key with the right to read profiles cannot start the browser: apps/server/test/api-keys.js

Questions

Do I need this screen?: Not unless you write scripts or connect an AI assistant. The rest of the program works the same with it switched off.
The switch is on but the status says Stopped.: The API could not start, and the reason is written right under the switch. Switch it off and on again once the cause is gone.
I regenerated the token and the assistant stopped working.: The client configuration carries the token. Press Copy config again, paste it over the old block and restart the assistant.
Can a website I visit reach the API?: A request that comes from a web page is refused, even with the right token. Scripts and the assistant on this computer are not web pages, so with the token they get through.
Does the assistant see my passwords?: Not proxy passwords: the proxy list comes without them. It can read the current two-factor code of a profile that stores a key.
How do I try it quickly?: Copy the line under Example request with the Copy button next to it and run it in a terminal: the usual one on macOS and Linux, PowerShell on Windows. It asks for your profile list with your own address and token.

Next to this

Try it with one script

The free plan gives two profiles, with no time limit and no card.

Download opens at launch Knowledge base