cursorrules

Driving Argus from this project

Argus is an anti-detect browser. A profile is an isolated browser identity with its own fingerprint, proxy and cookie jar. This project can drive those profiles either as MCP tools or over plain HTTP.

Before anything works

• The Argus launcher must be open. The API starts with it and stops with it. A refused connection almost always means the launcher is closed, not that the address is wrong.
• Base URL is http://127.0.0.1:39219. It listens on loopback, on this machine. Nothing off it can reach the API, and there is no hosted web API to point at instead.
• Auth is Authorization: Bearer <YOUR_API_KEY>. Keys are minted in the launcher's API tab and shown once — only a hash is stored, so a lost key is replaced rather than recovered.
• The first call from a new client blocks. The launcher raises an approve-or-deny card and holds the request until a human answers. Do not treat the pause as a hang, and do not retry — a retry queues a second card.

Rules that save a wasted turn

• A 403 is not a missing profile and is not worth retrying. It means the key is scoped to folders that do not contain that profile, or it is trying to author an automation while folder-scoped. Automations are shared across every folder and have none of their own, so authoring one needs an unscoped key.
• Creating a profile is available; purging one is not. argus_create_profile mints one — only name is required, and everything else takes the same defaults the app's own New Profile dialog uses. The asymmetry is at the other end: argus_delete_profile only moves a profile to Trash, where the app can restore it and the on-disk browser data stays, and it never sends permanent. An irreversible purge stays a human action in the app.
• Datasets are on the API in full. Creating one, replacing its declared columns, appending, updating and deleting rows, Trash and restore — all of it has a tool. Read with argus_query_rows (a list of {column, op, value} conditions, optionally aggregated) or argus_sample_rows for a page in insertion order; both are capped and paged, so plan on filtering rather than on pulling a dataset whole. Rows are indexed by column key, which never changes when a column is renamed — write against keys, not names.
• A launched session carries the profile's own identity. Whatever the profile already holds comes with it, including its cookies, so a profile with a cookie set assigned opens already signed in. Do not send it anything the profile is not meant to have.
• Sharing is enforced and it refuses. argus_assign_proxy is refused when the proxy would then be shared by more profiles than the user's limit allows, or when it would put two profiles for the same platform behind one exit; the refusal names the profiles already on it and the limit it was judged against. Repeating the call with acknowledgeSharing: true proceeds anyway — shared egress is a threshold rather than a prohibition — but that flag is for after the user has been told and has agreed, not for getting past a refusal on your own. A cookie set is stricter and is not a setting at all: exactly one profile may hold it, because two profiles on one set is one account signed in twice. argus_launch_profile blocks on neither, but its reply carries a warnings array when the profile is over a limit — say so rather than opening a batch silently, and call argus_sharing_report first, which returns the whole picture in one call instead of one refusal at a time.
• Proxy listings never return credentials. Do not plan around reading one back.
• The five page-driving tools need a profile that is already open. They attach over CDP to a running profile; launch it first. Every one of them takes profileId.
• Finish what was delegated instead of asking for it back. "Create an account", "set one up", "make a few profiles" name no username, no display name and no profile name — those are yours to invent. Choose them, do the whole job, report what you chose, and offer to change it afterwards. Save a question for what genuinely blocks you and only the user can answer.
• Ask the page, not the person. Whether a signup needs an email confirmation, a phone number or a captcha is answered by submitting the form and reading what comes back — not by asking in advance. And reach a form by navigating the site rather than guessing its URL: /signup, /register and /createuser are guesses, and on plenty of sites (Hacker News among them) the create-account form is a second form on the login page, told apart from the sign-in form by its fields rather than by its position.