SESSIONS & CONTROL
Set permissions for browser agents
Give each agent its own credential and browser cap. Treat permission to control a signed-in browser as permission to use the accounts inside it.
Keep administrator and agent access separate
ADMIN_SECRET signs you into the dashboard. Create an agent there and use its bearer token for MCP. Each agent has its own scopes and browser cap, so you can withdraw one client's access without sharing your administrator password.
Agent tokens have no expiry and can be rotated or revoked. OAuth connections create connector agents with access and refresh tokens. You can disconnect a connector on the Agents page.
Five scopes need an explicit grant
| Scope | What it permits |
|---|---|
| seed:use | Use profile templates that can contain copied logins. |
| seed:write | Save or update a profile from an owned browser. A loan does not permit exporting its logins. |
| browser:lend | Lend an agent's browser to another agent under the lending rules. |
| browser:borrow | Ask another agent for its browser under those same rules. |
| browser:tunnel | Bind one private host and port to a browser through a tunnel. |
These scopes are not part of the default grant. Tick them when you create an agent, change them later under Agents, Permissions, or use PATCH /api/v1/agents/:id. Review the full permission set before sending a change; a scope name alone does not explain which accounts a browser holds.
Native Chrome access is a separate dashboard toggle, Allow agent control, not a scope. New agent-owned browsers start with it on; TALLYLAMP_AGENT_DESKTOP_DEFAULT=0 starts them with it off. When it is off, the agent is told to ask you to turn it on and wait.
Proxy edits use the owner's browser-control permission and require the browser to be stopped. A borrower uses its existing route but cannot change it. Proxy credentials are never returned in browser listings.
When an agent asks for one of your browsers
From Tallylamp 0.8.0 an agent can ask you for a browser you own. It needs no scope to ask. The request appears on Browsers with the agent's name, the browser, the level it wants and its reason, and a count on the Browsers link shows it from other pages.
Asking is rate-limited instead: two requests a minute and three waiting at once per agent. An agent that asks again for the same browser keeps its place in the queue.
| Level | What the agent can do |
|---|---|
| Read | List tabs, read snapshots, take screenshots, and see console and network activity. It cannot navigate, click, type or run scripts, and it never takes the browser from you. |
| Control | Everything the owner's agent can do in the page, signed in to every account the profile holds. |
Check who is asking
Read the agent's name and reason. Approve only a browser whose accounts you are willing to hand over at that level.
Pick the level
Approve control, or choose Approve read only. You can always give less than was asked for, never more.
Pick how long
From 30 minutes to 24 hours, or until you revoke it. A read request starts at until-revoked, and a control request at 8 hours.
Revoke when done
The browser's page lists everyone with access, their level and when it ends. Revoke takes effect on that agent's next call.
Use browser caps to bound active work
An agent's browser cap and the deployment's fleet limit serve different purposes. Neither is set by default. Set a cap for an agent, or TALLYLAMP_MAX_BROWSERS for the deployment, when you want a limit. Once a fleet cap is set, a browser creation failure can mean the fleet has no free slots even when the agent is allowed to create browsers.
Names and project metadata help you identify a browser, but they cannot change who created it. Tallylamp records the authenticated creator, even if an agent submits metadata that claims a human source.
Profiles share the server's isolation boundary
Separate permissions govern access through Tallylamp. Inside one deployment, the Chrome processes share a container and Unix user. A separate profile is not a separate virtual machine.
This matters especially on hosts where Chrome's renderer sandbox cannot run. In auto mode, Tallylamp can fall back to --no-sandbox and report fell-back in the dashboard. Set TALLYLAMP_SANDBOX=on if you want Chrome to refuse to start without a working sandbox.
Revoking access leaves saved profiles on disk
Disconnecting a connector prevents that client from using Tallylamp, but does not remove cookies from its browsers. If a profile was compromised, deal with the saved browser and revoke sessions at the affected website too. Rotating an MCP token cannot revoke a website's own session.
Docs behind this guide
Based on Tallylamp's documented behaviour. See the source for API details and release-specific settings.