> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenforge.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments & Sessions

> How Director authenticates into your product before recording.

Most real demos need to start signed in. An **environment** is a saved target app — a base URL plus however Director should get authenticated before recording starts.

## Session lifecycle

A captured session moves through these states (`sessionStatus`):

| Status     | Meaning                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `pending`  | No session captured yet.                                                                          |
| `captured` | A session was just uploaded, not yet checked against the live app.                                |
| `checking` | A verification run is in progress (`verify_environment`).                                         |
| `active`   | Verified and usable — demos against this environment will restore it.                             |
| `expired`  | The session aged out (see `sessionLineageMaxAgeMs` below) or a re-check found it no longer works. |
| `rejected` | Verification actively failed (e.g. redirected to a login page).                                   |

## Getting a session in

<Tabs>
  <Tab title="Pairing code (recommended)">
    Your agent creates an environment and mints a single-use pairing code (`create_login_code`), valid for 30 minutes. Send that code to whoever can log into your product, and have them run:

    ```bash theme={null}
    director session DIR-XXXX-XXXX-XXXX
    ```

    On your machine, this opens a real Chromium browser, you log in, and once you press Enter, Director captures and uploads your session (cookies and local browser storage). No API key ever touches your machine — the code itself is the credential, single-use and time-limited.

    MCP tool responses that include a pairing code automatically carry a ready-to-paste `loginCommand` field with this exact command pre-filled.
  </Tab>

  <Tab title="Username/password">
    Pass `credentials: { username, password }` on the environment (or directly on a one-off demo). Director fills a plain login form itself — off-camera, before recording starts. Credentials are never persisted to the demo record and never sent to the model.
  </Tab>

  <Tab title="CI / automated">
    ```bash theme={null}
    director session --api-key $DIRECTOR_API_KEY --environment <id>
    # or, to create the environment inline:
    director session --api-key $DIRECTOR_API_KEY --name staging --base-url https://staging.example.com
    ```
  </Tab>
</Tabs>

## Keeping sessions fresh

* **`reset` hook** — an optional URL Director calls to reset your app to a known state (`before`, `after`, or `both` relative to the recording). Configurable method and timeout. By default, an unreachable reset hook fails environment creation — pass `skipResetVerification: true` to opt out.
* **`settle`** — how Director knows the page has finished loading after navigation or login: a selector to wait for, a URL substring, and/or a flat delay.
* **`sessionLineageMaxAgeMs`** — how long a captured session is trusted before it's treated as expired (default 30 days, 1–365 day range).
* Sessions can be wiped without deleting the environment itself via `delete_session` — useful when you know credentials rotated and want to force a fresh capture.

## Reset secrets

Creating an environment returns a one-time `resetSecret` — use it to authenticate calls *from* your app's reset endpoint back to Director, if your reset flow needs to prove the request is legitimate.