Skip to content
valetkey

The managed browser

The managed browser is a real Chrome window running a profile that belongs to valetkey. Because valetkey holds a debugging connection to it, sessions go in live: switching personas is one command, with no restart and no files to wire up.

Terminal window
valetkey browser

That prints the profile path and the local endpoint, and leaves Chrome running. Sessions land in it whenever you sign in:

Terminal window
valetkey login admin

The next page load is signed in as admin. Run valetkey login free-user and the same window is now the other user; valetkey clears the previous session for your configured origins before injecting the new one, so you never end up half signed in as two people.

Why a separate profile

Section titled “Why a separate profile”

Each app gets its own profile under ~/.valetkey/profiles/<app>, holding nothing but that app’s dev sessions. Your personal Chrome, with your real logins, is never touched. This is also what Anthropic recommends for browser-using agents: give the agent a profile that has nothing valuable in it.

Injection goes through the debugging connection rather than page JavaScript, which is what lets valetkey set httpOnly cookies. Those are the ones that matter, since almost every real session cookie is httpOnly and page scripts cannot touch them.

Connecting agent tools to it

Section titled “Connecting agent tools to it”

valetkey browser --print-devtools-config prints ready-to-paste config for the two MCP servers that can drive an existing Chrome:

  • Chrome DevTools MCP with --browserUrl http://127.0.0.1:<port>
  • Playwright MCP with --cdp-endpoint http://127.0.0.1:<port>

Both share the browser with valetkey: they drive pages, valetkey manages who is signed in. The port is ephemeral and changes each launch, so print the config again after a restart, or read it from valetkey state.

For Claude in Chrome, install and connect the extension inside the managed window once. From then on Claude browses a profile whose session valetkey controls, and valetkey login <persona> (or the valetkey_login_as MCP tool) changes who Claude is.

Checking on it

Section titled “Checking on it”
Terminal window
valetkey state

Prints the port, process id, start time, and profile path, or tells you nothing is running. valetkey browser --stop makes valetkey forget the browser so the next launch starts fresh; quit the window yourself if it is still open.

Things worth knowing

Section titled “Things worth knowing”

You can close valetkey’s tabs whenever you like. It keeps one working tab for navigation and storage access, and reopens it on demand if it is gone.

Your dev server needs to be up for sessions that carry localStorage, because writing localStorage requires loading the origin. Cookie-only sessions inject fine with the server down. If the server is unreachable, valetkey says so instead of hanging.

Verifying it yourself: nr smoke:browser in a clone drives real Chrome through injection, persona switching, and logout. VALETKEY_DEBUG=1 traces every browser call to stderr when something looks wrong.

Only the origins in your config are ever touched, both when injecting and when clearing. Cookies for anything else in that profile, including the Claude extension’s own sign-in, are left alone.