Quick start

apus browser --browser-profile apus doctor
apus browser --browser-profile apus doctor --deep
apus browser --browser-profile apus status
apus browser --browser-profile apus start
apus browser --browser-profile apus open https://example.com
apus browser --browser-profile apus snapshot

"Browser disabled" means the plugin or browser.enabled is off; see Configuration and Plugin control.

Browser control errors name the recorded policy refusal or plugin load failure. If browser is excluded from plugins.allow, add it to the existing list before running apus plugins enable browser; restarting alone cannot repair that policy. Follow the error's enablement or Doctor command. If no availability reason is recorded, run apus doctor and check the Gateway logs.

If apus browser is missing entirely, or the agent says the browser tool is unavailable, jump to Missing browser command or tool.

Plugin control

The default browser tool is a bundled plugin. Disable it to replace it with another plugin that registers the same browser tool name:

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

Defaults need both plugins.entries.browser.enabled and browser.enabled=true. Disabling only the plugin removes the apus browser CLI, browser.request gateway method, agent tool, and control service as one unit; your browser.* config stays intact for a replacement.

Profiles, launch settings, snapshot defaults, tab cleanup, and browser.allowSystemProfileImport hot-reload. Import permission changes apply to new imports; an import already in progress keeps its admission. Browser enablement, evaluation, SSRF policy, and extension relay settings require a Gateway restart. See Config hot reload.

Agent guidance

Tool-profile note: tools.profile: "coding" includes web_search and web_fetch, but not the full browser tool. To let the agent or a spawned sub-agent use browser automation, add browser at the profile stage:

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

For a single agent, use agents.entries.*.tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] alone is not enough because sub-agent policy is applied after profile filtering.

The browser plugin ships two levels of agent guidance:

• The browser tool description carries the compact always-on contract: pick the right profile, keep refs on the same tab, use tabId/labels for tab targeting, and load the browser skill for multi-step work.
• The bundled browser-automation skill carries the longer operating loop: check status/tabs first, label task tabs, snapshot before acting, resnapshot after UI changes, recover stale refs once, and report login/2FA/captcha or camera/microphone blockers as manual action instead of guessing.

Plugin-bundled skills are listed in the agent's available skills when the plugin is enabled. The full skill instructions load on demand, so routine turns do not pay the full token cost.

For page text, use a selector-scoped snapshot or act:evaluate that returns only the relevant text or structured data, then let the active agent model reason over that bounded result. Use efficient snapshots for controls and action discovery; they intentionally omit most non-interactive prose.

Missing browser command or tool

If apus browser is unknown after an upgrade, browser.request is missing, or the agent reports the browser tool as unavailable, the usual cause is a plugins.allow list that omits browser and no root browser config block exists. Add it:

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

An explicit root browser block (any key under browser, such as browser.enabled=true or browser.profiles.<name>) activates the bundled browser plugin even under a restrictive plugins.allow, matching bundled channel config behavior. plugins.entries.browser.enabled=true and tools.alsoAllow: ["browser"] do not substitute for allowlist membership by themselves. Removing plugins.allow entirely also restores the default.