> ## 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.

# 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:

```dotenv theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": 1,
  "provider": "local",
  "viewport": { "width": 1280, "height": 800 },
  "sessionMode": "write-access"
}
```

<ParamField path="version" type="number" required>
  Config schema version.
</ParamField>

<ParamField path="snapshotModel" type="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.
</ParamField>

<ParamField path="provider" type="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"`.

  <Note>
    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.
  </Note>
</ParamField>

<ParamField path="viewport" type="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.
</ParamField>

<ParamField path="sessionMode" type="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.
</ParamField>

<ParamField path="windowPosition" type="object">
  Optional, manually set. Sets the initial position of the headed browser window on screen. Has no effect in headless mode.
</ParamField>