Skip to content

Isolated vs Attached

An agent that uses a browser or a desktop can work in its own environment, separate from any person's, or attached to the user's own browser or screen. Isolated is the default and the safe choice; attached mode is supported, but never implicit.

The deployment matrix

Mode Browser Desktop Where std-tools must run Default
Isolated — the agent's own environment launch: its own headless Chromium, with a fresh profile per session virtual: its own virtual display, with an optional view so a person can watch The client's sandbox container — the normal deployment Yes
Isolated, persistent persistent: its own Chromium on a saved profile, usually headed, so a person can sign in once and watch — A container with a display, or the user's machine Opt-in
Attached — the user's environment cdp: attach to a Chrome the user started with remote debugging host: operate the real screen of the machine The user's own machine (a local agent) Opt-in, with safeguards

A process inside a sandbox container cannot reach the user's screen or browser. Attached mode therefore needs a deployment where std-tools runs on the user's machine — for example a desktop application that embeds the toolkit — or where the user deliberately exposes a browser endpoint to it.

Isolated: launch (the default)

std-tools starts its own headless Chromium. Each MCP session gets a fresh, credential-free browser context, so cookies and storage are never shared between sessions or with any person's browser. Every connection Chromium makes goes through the egress proxy, with the domain lists, the private-address block and IP pinning (Security). Nothing to configure beyond DPTTOOLS_ENABLE_BROWSER=true.

Isolated, persistent: a saved profile

For sites that need a person to sign in — a portal with two-factor authentication, say — use a saved profile that std-tools launches itself:

DPTTOOLS_BROWSER_MODE=persistent
DPTTOOLS_BROWSER_PROFILE_DIR=/workspace/.browser-profile   # required
DPTTOOLS_BROWSER_HEADLESS=false                            # so a person can see it and sign in
  • A person signs in once in the visible window; the login is kept in the profile folder.
  • Only one session at a time, because a profile folder cannot be shared between browsers.
  • A headed browser needs a display: the user's desktop, or a container with a virtual display and a viewer.
  • The egress proxy still applies, because std-tools launched the browser.
  • The profile folder holds the site's session cookies: protect it like a credential.

Attached: the user's own browser (cdp)

In cdp mode the agent drives a Chrome that the user started:

  1. Start Chrome with a dedicated profile and remote debugging (the executable's name and path depend on the platform):

    chrome --remote-debugging-port=9222 --user-data-dir="$HOME/agent-chrome-profile"

    Chrome 136 and later refuse remote debugging on the default profile — Google made the change because attackers used the debugging port to steal cookies — so an agent cannot attach to the user's everyday profile. The user signs in to what the agent needs in this dedicated profile.

  2. Point std-tools at it:

    DPTTOOLS_ENABLE_BROWSER=true
DPTTOOLS_BROWSER_MODE=cdp
DPTTOOLS_BROWSER_CDP_URL=http://127.0.0.1:9222

What changes in cdp mode:

  • The agent works only in tabs it opened, unless DPTTOOLS_BROWSER_CDP_SHARE_TABS=true lets it see and use the user's other tabs.
  • No egress proxy, so no IP pinning. std-tools did not launch the browser, so it cannot route its traffic. The agent's own tabs are checked request by request — the domain lists and the private-address block — but connections cannot be pinned to a validated address.
  • Whoever reaches the debugging port controls the browser completely. Keep it on 127.0.0.1 and never expose it beyond the machine.
  • fetch_webpage_rendered uses a separate headless browser, never the user's.

The confirmation gate is off by default in every mode, so in attached mode especially:

  • Get the user's consent before an agent takes over their browser, and tell them that what is on screen goes to the model provider.
  • Approve consequential actions in your application — toolkit hooks on the browser_* tools — or set DPTTOOLS_BROWSER_CONFIRM=deny. See Using with the Toolkit and Security.

Isolated: a virtual desktop (virtual, the default)

The computer server's default backend gives each MCP session its own Xvfb display inside the container, with a light window manager. The agent sees only the applications it starts there, and sessions never see each other's desktops.

DPTTOOLS_ENABLE_COMPUTER=true
DPTTOOLS_COMPUTER_BACKEND=virtual          # the default
DPTTOOLS_COMPUTER_DISPLAY_SIZE=1440x900    # the default
DPTTOOLS_COMPUTER_VNC_PORT=5900            # optional: a person can watch or take over
  • Linux only: the image needs xvfb, xdotool and a window manager such as openbox (Deployment).
  • The agent starts applications with execute_command, on the display its results name: DISPLAY=:99 libreoffice --calc report.xlsx &.
  • At most DPTTOOLS_COMPUTER_MAX_SESSIONS (2) desktops are open at once; one unused for 10 minutes is closed.
  • The VNC view needs x11vnc. It listens on 127.0.0.1 inside the container (the first session on the port you set, the next on port + 1), without a password, so a plain port mapping does not reach it: connect through something you control that shares the container's network, such as an SSH tunnel, and never expose it more widely.
  • A virtual desktop needs no network.

Attached: the user's real screen (host)

In host mode the agent operates the real screen, mouse and keyboard of the machine std-tools runs on — so std-tools must run on the user's machine, not in a container.

DPTTOOLS_ENABLE_COMPUTER=true
DPTTOOLS_COMPUTER_BACKEND=host
DPTTOOLS_COMPUTER_MONITOR=primary           # or a monitor number
DPTTOOLS_COMPUTER_KILL_HOTKEY=ctrl+alt+shift+k
  • Platforms: Windows and Linux X11. macOS is untested (it needs Accessibility and Screen Recording permission); Wayland is not supported. On Linux, install pynput separately: pip install python-xlib && pip install --no-deps pynput.
  • One session at a time, because there is one real cursor. A second client is refused until the first has been idle for a minute.
  • The person stays in control. Moving the mouse into the top-left corner of the screen, or pressing the kill hotkey, stops the agent until the server restarts. If the person moved the mouse or typed in the last second, the next action is refused. On Linux X11 the pause and the corner work between actions only; the hotkey works at any time.
  • Everything on the screen goes to the model provider, in every screenshot. Close what the agent should not see.
  • Get the user's consent before an agent takes over their screen in host mode, and tell them what is on screen goes to the model provider. DPTTOOLS_COMPUTER_CONFIRM=elicit asks for that consent at the start of each host session, in MCP clients that support elicitation.
  • Approve consequential actions in your application — toolkit hooks on the computer_* tools — because the desktop gate cannot tell what a click will do. See Using with the Toolkit and Security.