Shared browser

Watch agents use a real Chromium browser on your Koyd Server, take control when they need you, and review their screenshots and recordings.

One browser for you and your agents

Koyd Server runs a real Chromium browser that you and your sessions share. Open it from View → Browser in the workspace header, or press Ctrl+Shift+B (Cmd+Shift+B on a Mac). Pages run on the server and stream to the device you are using, so the browser also works from a phone or tablet.

Because the browser runs on the server, localhost means the server machine. A development app running on the server opens in the panel even when you work from another device. Open in default browser opens the current address on your own device instead, where localhost points to that device.

You can browse in personal tabs without giving any session access. The bar above each page shows who controls the tab: you, or the session that opened it.

Set up the browser

Each instance downloads Chromium once. When the browser panel shows Set up browser, choose it; you can keep working while setup finishes. You can also run the command below on the server. On Linux, add --with-deps to install the system libraries Chromium needs.

Command

koyd browser install

Chromium starts only when a page opens. If pages fail to start later, open Browser settings from the gear in the browser panel, choose Settings, and use Run setup again under Maintenance. It checks the browser download and leaves your saved sessions alone.

Let a session use the browser

Type /tools in the session’s message box.
Turn on Browser use. If the browser is not set up yet, Koyd shows Open browser setup instead of enabling it.
Ask the session to open a website or your local development app. Its tabs appear in the browser panel.

Browser use starts off and is saved per session, across restarts. The Tools pill beside Skills and MCPs lists what is enabled; change it with /tools. To turn it on for new sessions, use Lab → Tools → Session tools. Only main sessions can use the browser: agent and swarm child sessions do not get it, and read-only modes cannot use it.

Good to know · Turning on Browser use never shares your personal tabs. Turning it off stops the session’s browser work and returns its tabs to you.

Watch, take control, and hand back

Session tabs carry a dot in the tab strip, and the bar above the page names the session that controls the tab. Watching does not change the page’s input or size, and selecting a different chat never moves a tab to another session.

Choose Take control to use the page yourself. The page, its state, and its sign-in stay as they are. The agent’s queued browser actions are cancelled and an unfinished recording is discarded.
Do what you need: sign in, fix a form, or move to another page. If you go to a different website, resuming gives the session access to that website.
Choose Resume agent to hand the tab back. The agent takes a fresh look at the page before its next action.

Browser settings → Sessions lists the sessions with open tabs under Open now, with their state and current site. Use View to jump to a session’s tab, or Take control and Resume agent right there.

Good to know · Taking control stops what happens next. It cannot undo a request the website already received.

Separate sign-ins in every tab

Every tab has its own private browser profile. Tabs do not share cookies or site storage, even within one session, and the sign-ins from your usual browser are not available. That keeps sharing and revoking a single tab predictable.

Website data stays in memory. Closing a tab or restarting the server signs you out of the sites in it. One exception: when a page in your personal tab opens a link in a new window, Koyd opens it in a new tab that keeps the sign-in.

When the agent needs you

An agent with Browser use can ask you to take over, for example to sign in or to solve a check it cannot complete. A card appears above the message box with the agent’s explanation, and the session’s indicator in the sidebar shows that it is waiting for you. Ask user does not need to be on.

Choose Open browser to go to the session’s tab. You already have control.
Finish the step in the page.
Choose Resume agent. The same task continues without a new message, and the agent checks the page before its next action.

The pause takes effect at a safe point. New browser actions stop at once; a model reply or command that is already running finishes first, and the card shows that the session is pausing until it does. Choose Stop turn to cancel the task instead. A message you send in the meantime waits in the session’s queue.

Reloading Koyd or closing the browser panel does not resume the agent. Turning off Browser use, switching to a read-only mode, or revoking the tab cancels the task instead of resuming it, and a server restart interrupts it.

It behaves like a regular browser

Websites see a regular Chromium browser, so sites that turn away automated browsers work normally.
The live view updates as soon as the page changes. It is built for working with pages, not for watching video or listening to audio.
A link that opens a new window opens in a new tab that keeps your sign-in. In session tabs, the agent follows such links in the same tab. Pop-ups that submit a form show Pop-up blocked with Open externally.
Alerts, confirmations, prompts, and leave-page warnings in a tab you control appear above the page with their buttons. Unanswered dialogs close after a minute; agent tabs dismiss them automatically.
Link clicks show loading, single-page apps update the tab title, and failed navigations explain what went wrong. Slow sites get up to 30 seconds, and Stop is always available.
Downloads are cancelled, and a notice tells you so.
On a phone, drag to scroll and tap to click. On a Mac, Command shortcuts work in the page. Copy and cut put the page selection on your device’s clipboard, and paste works too.

The toolbar has back, forward, reload, the address field, and Find on page, plus zoom and a 390-pixel mobile width for checking layouts.

Send page context to a chat

The message box below the page sends page context to the selected session. Choose Attach element and click parts of the page (Shift+click for more, Escape to finish), or highlight text and choose Attach text. Element attachments include the element’s HTML and computed styles. Screenshot attaches the visible page, and each attached element has its own crop button. You can attach up to six parts at a time.

Write your message and choose Send to chat, or Queue in chat while the session is busy. The page address goes with it. These tools work in tabs you control, with or without Browser use.

Screenshots and recordings

Ask the agent for a screenshot or a recording of what it does. Captures appear in the chat and stay there after the tab closes, after server restarts, and in session exports. Recordings are real video at up to 25 frames per second, with a visible cursor and click highlights. While recording, the pointer moves and text is typed at a natural pace, and the time the agent spends thinking is trimmed. A recording stops at ten minutes or close to 64 MB and keeps what it captured.

Password fields, one-time code fields, and fields a site marks as private are masked in every screenshot and recording the agent takes.

Select a capture to open the media viewer. Recordings have playback speed controls, and you can close the viewer by clicking outside the media.

+ / -: Zoom in or out
0: Fit the image
← / →: Previous or next screenshot
Esc: Close the viewer

To find older captures, open Browser settings → Sessions. Saved sessions lists your sessions with a search field; choose one to see its screenshots and recordings or to open its chat. Each session keeps up to 1,000 captures and 512 MB. Permanently deleting a session removes its captures.

Tabs, limits, and cleanup

An instance holds up to 24 tabs, with at most eight per session and eight personal tabs.
Agent tabs that nobody views close after 15 idle minutes. Shared tabs and tabs you control stay open until you close them or the server restarts.
Deleting a session closes the tabs its agent opened and revokes tabs you shared with it.
Disconnecting a device never hands control of a tab to anyone else.
Updating Koyd restarts the server, which closes every tab and stops browser work in progress.

Optional computer use on the server’s desktop

Computer use is a separate session tool. It lets an agent operate desktop apps on the server’s own desktop, with the apps and accounts already signed in there. It needs a real desktop session. A server without one, such as a typical VPS, still runs the shared browser, terminals, Git, and everything else.

Type /tools in the session and turn on Computer use.
Choose the settings button next to Computer use, then Check access. Fix any permission it reports.
In a mode that can make changes, ask the session to work in an open app. For example: Find Calculator and work out 24 × 17.

Only one session can control the desktop at a time, and control is released after two idle minutes. The settings dialog shows each session’s current app and activity; Stop pauses a session until you choose Resume. Turning Computer use off stops it for that session, and read-only modes cannot use it. Keep my cursor free limits the agent to background accessibility actions, so it never moves your mouse or types with your keyboard; some apps only work with it off.

Windows: keep the desktop signed in and unlocked. Apps running as administrator may need to be reopened normally.
macOS 14 or later: after Check access, enable Accessibility and Screen Recording for pi-computer-use.app in System Settings → Privacy & Security, then choose Recheck.
Linux: a graphical session with accessibility (AT-SPI2) enabled. On X11 the agent can take screenshots and use the mouse and keyboard; on Wayland it can use accessibility controls only.

Good to know · Computer use acts in your real apps with your real accounts, and screenshots of the screen go to the session’s model. Close anything private first, watch the session, and stop it if something looks wrong. Completed actions cannot be undone, and how well it works varies by app.

What Koyd keeps and logs

The chat records each browser and desktop action the agent takes, with its result.
Screenshots and recordings stay with the session until you permanently delete it.
Website cookies and storage live only in memory and disappear when the tab closes or the server restarts.
The server’s operation audit records which device ran which operation and whether it succeeded. It does not store page content or what you type, and it leaves out pointer movement, scrolling, and clipboard reads.
Screenshots the agent reads are sent to the session’s model provider, like other message content.

Good to know · These controls guard the browser and desktop tools. They do not sandbox a session that has full access to your project, and they do not make website content safe to follow.