Skip to main content

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

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"
}
​
version
number
required
Config schema version.
​
snapshotModel
string
Deprecated. This key is ignored by npx libretto snapshot, which now prints a compact accessibility tree directly instead of using a configured analysis model.
​
provider
string
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.
​
viewport
object
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.
​
sessionMode
string
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.
​
windowPosition
object
Optional, manually set. Sets the initial position of the headed browser window on screen. Has no effect in headless mode.