Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Configuration

Change viewport, browser provider, or other workspace settings after initial setup.
Both npm create libretto@latest and npx libretto setup handle initial configuration for you. The commands on this page are for changing settings after the fact.

Environment variables

Libretto automatically loads the repo root .env file before running CLI commands. Put provider credentials there:
# inside .env
KERNEL_API_KEY=<kernel-api-key>
BROWSERBASE_API_KEY=<browserbase-api-key>
BROWSERBASE_PROJECT_ID=<browserbase-project-id>
STEEL_API_KEY=<steel-api-key>
Use .libretto/config.json for persistent workspace preferences like the default browser provider.

Config file reference

The config file is at .libretto/config.json. You can edit it directly.
{
  "version": 1,
  "provider": "local",
  "viewport": { "width": 1280, "height": 800 },
  "sessionMode": "write-access"
}
path versionnumberrequired
Config schema version.
path snapshotModelstring
Deprecated. This key is ignored by npx libretto snapshot, which now prints a compact accessibility tree directly instead of using a configured analysis model.
path providerstring
Optional. The browser provider to use. Must be "local", "kernel", "browserbase", "steel", or "libretto-cloud". Defaults to "local". Can be overridden per-command with --provider or the LIBRETTO_PROVIDER environment variable. Resolution order: --provider flag → LIBRETTO_PROVIDER env var → this config field → "local".
If you deploy to a cloud host using kernel, browserbase, steel, or libretto-cloud, set provider here too. Then local open, run, and debugging use the same browser as production — the container's Chromium isn't identical to your local one, and the drift causes inconsistent rendering and timing.
path viewportobject
Optional, manually set. Default browser window size (width and height in pixels) used by open and run when you don't pass --viewport. Defaults to 1366x768 if not set.
path sessionModestring
Optional, manually set. Default access mode for new sessions created by open, connect, and run. Must be "read-only" or "write-access". Defaults to "write-access" when omitted. Pass --read-only or --write-access to open, connect, or run to override when creating a session.
path windowPositionobject
Optional, manually set. Sets the initial position of the headed browser window on screen. Has no effect in headless mode.
Powered byHolocron