Docs/Tutorials/Give an agent a browser
Tutorials

Give an agent its own browser

7 min read

Sooner or later you ask an agent to do something on the web that sits behind a sign-in: check an order, read a dashboard, file a form. The obvious move - let it use your browser - is the wrong one, twice over. Technically it no longer works: Chrome and Edge refuse to be remote-controlled on your everyday profile, and they encrypt its saved logins so they cannot be copied out. And even if it did work, you would not want it: a browser holds your whole life, and an agent driving it would be acting as you, everywhere, with every account you have ever stayed signed in to.

DevThrottle's answer is a browser profile: a real browser - Chrome, Edge, Brave or Opera - running in a separate profile of its own: its own folder on disk, its own sign-ins, starting completely empty. You sign it in once, by hand, to exactly the accounts you want an agent to reach. From then on an agent on that machine can drive it - click, read, fill forms - through Browser Harness, the browser-driving tool DevThrottle installs for you. What the profile can act as is precisely what you signed in, nothing else.

About ten minutes, most of it you signing in. You need the Director open, and Chrome, Edge, Brave or Opera installed on the machine. The command line steps at the end additionally need a working Gateway and a shell spawned by a DevThrottle session - that is where the environment they ride on is already set; anywhere else you supply the three variables (named in the note below) by hand.

  1. Open Browser profiles

    In the Director, click Browser profiles - it is a pinned row in the left rail, and also a menu of its own in the menu bar. Both land on the same place: the Browser profiles tab in Settings. On a machine with no profiles yet, the tab opens on a full explanation of what a profile is, ending in a + Create browser profile button.

    If a banner titled Turn on browser control is showing, click Install Browser Harness first. Browser Harness is the tool DevThrottle uses to drive these profiles, made by browser-use; DevThrottle installs it for you, into its own environment. Your profiles work without it - they just cannot be driven until it is installed.

  2. Name it after the identity it will hold

    Click + Create browser profile at the bottom of that explanation - on a machine with no profiles yet, it is the only create button on the screen. (Once at least one profile exists, the explanation gives way to a short header whose + New browser profile button opens the same form.) The form asks one question that matters: what will this profile be signed in as? Name it after the identity - Work, Personal, a client's name - not after what you plan to do with it. "Acme Corp" tells you what an agent can reach when you point it there; "testing" tells you nothing, six weeks from now.

    Pick which browser underneath - only browsers actually installed on this machine are listed - and click Create and sign in. You are creating a brand new, empty profile, not adopting one you already use. Your everyday browser keeps running, untouched: not its tabs, not its bookmarks, not its logins.

  3. Sign it in once, by hand

    A new browser window opens, and the Director asks you to sign in to whatever you want this profile to hold. This is the step that cannot be automated, on purpose: you type the credentials in the browser window yourself. DevThrottle opens the page, never types, and never sees a password.

    Two routes, both legitimate. Signing in to a Google account (Chrome) or a Microsoft account (Edge) carries a whole profile across in one go. Or skip that and sign in to just the individual websites this profile is for - which is how you keep a client profile to exactly that client's portal and nothing else. When you are done, click Done - I am signed in. The logins live in the profile's own folder, so stopping the browser or restarting the machine does not clear them - though any site can still sign the profile out on its own schedule, exactly as it could sign you out.

  4. Read the card back

    The profile now has a card on the Browser profiles tab: its name, which browser it is, the account it is signed in to, and a status - Ready when it is running and you have confirmed a sign-in, Needs sign-in when it is running but no sign-in has ever been confirmed, Stopped when it is not running. Be precise about what that means: the card checks that the browser is up and remembers that you once said "Done" - it does not re-check whether the sites still consider the profile signed in. If a site signs it out later, the card still reads Ready; the tell is an agent reporting a login page, and the fix is opening the window and signing in again by hand.

    The card offers the actions that fit its state: a stopped profile offers Start; a running one offers Stop, plus Sign in once if it has never been signed in or Copy attach command if it has. Stopping a profile keeps its logins; the trash button removes the profile and permanently deletes its folder, sign-ins and all.

    The pinned rail row now shows your profile count, with a green dot when at least one is running - your one-glance answer to whether an agent has a browser available right now.

  5. Point an agent at it

    Three things have to be true before an agent's clicks land in this profile: the profile is running, the two attach variables are set, and the thing doing the clicking is Browser Harness - the only tool that reads them. None of that happens by itself, and for an agent it must all happen in one shell: each command an agent runs is its own process, so a variable exported in one tool call has vanished by the next. The shape that works is a single block - start, attach, drive:

    One shell, end to end: start, attach, drive
    cc-devthrottle browser start 'work'
eval "$(cc-devthrottle browser attach 'work')"
browser-harness <<'PY'
new_tab("https://example.com")
print(page_info())
PY

    Line by line: start launches the profile's browser if it is down - attaching does not start anything, and with the profile stopped the address the variables point at simply refuses to answer. attach prints the two variables Browser Harness reads, BU_NAME and BU_CDP_URL, as shell export lines the eval applies to the rest of the block. The browser-harness lines then drive the profile: open a tab, read the page back - and the read-back is your proof the attach worked. The export form is made for a POSIX shell; in PowerShell run the attach command bare to see the two values, then set them yourself before invoking the harness in that same shell:

    PowerShell
    cc-devthrottle browser attach 'work'   # prints the two values
$env:BU_NAME = 'work'
$env:BU_CDP_URL = 'http://127.0.0.1:9310'   # the port the attach output printed

    Those variables do not redirect an agent's built-in web tools, and telling an agent a profile name does nothing on its own - the agent has to run this block itself. DevThrottle installs the browser-harness tool; teaching your agent to reach for it is yours to set up: put the block above, with the profile name to use, where your agent reads its standing instructions - the repository's agent instructions file (a CLAUDE.md or AGENTS.md) or a skill, whichever your agent supports. From there its browser work lands in the profile, already holding the sign-ins you gave it. The full lifecycle is on the command line too: cc-devthrottle browser list, create, signin, start, stop, attach, rename, remove.

Warning
A signed-in profile is a credential. An agent driving it acts as whoever is signed in there - it can do anything those accounts can do, on every site they reach. Profiles do not make that risk disappear; they make it explicit and chosen. Which identity an agent holds becomes a decision you made once, on purpose, when you signed the profile in - never something it inherits by borrowing the browser you live in. So make one profile per identity, sign each in to only what that identity needs, and give a client profile that client's accounts and nothing else.
Note
The cc-devthrottle browser commands reach the profile through your Gateway, using three environment variables: CC_GATEWAY_URL, CC_GATEWAY_SESSION_KEY and CC_DIRECTOR_ID. A session DevThrottle spawned carries all three already - the commands just work there. A terminal you opened yourself does not, and the commands say so rather than guessing.
Note
On disk, a profile is a folder of its own under DevThrottle's data directory, plus a fixed local debugging port from a range reserved for browsers (9310 to 9499). The range starts where it does deliberately: it sits well above 7879-7898, the range older Directors listened on, so an old install mid-upgrade can never collide with a browser - today's Director has no listening port of its own. The browser's port answers only on the machine itself, which is why a profile belongs to one machine and only agents on that machine can drive it - like repositories, browsers are per-machine.
Tip
The first sign-in is the whole setup cost, and it survives restarts of the browser, the Director and the machine - the logins sit in the profile's own folder, held for as long as the sites themselves keep the session. Set up the two or three identities you actually use once, and from then on giving an agent the web is handing it the one start-attach-drive block above.

Next

The browser verbs are one corner of a larger command line surface - Driving DevThrottle from a script walks the rest of it, from reading your fleet as text to putting commands on a schedule.