A `Session` stores a View's browsing data, including cookies, local storage, IndexedDB databases, and cached resources.

You can choose between temporary (in-memory) sessions or persistent (on-disk) sessions, and decide whether Views share sessions or run in isolation.

> 📘 Sessions in AppCore
>
> In AppCore, `App::Create()` manages sessions for you, writing to an OS app-data folder by default. You can change the session path by specifying `Config::cache_path`.

## Using the Default Session

To assign the default session to a new View, pass `nullptr` for the session parameter.

```cpp
///
/// Passing nullptr for the Session gives this View the default session.
///
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), nullptr);
```

The renderer creates this session automatically during `Renderer::Create()`. It is a persistent session named `default`, and most applications do not need any other session.

You can also retrieve it directly by calling `Renderer::default_session()`.

## Choosing Session Persistence

Call `Renderer::CreateSession()` to create a session, then pass it to `Renderer::CreateView()` (see [Creating Views](/docs/2.0/creating-views)).

| Session Type | `is_persistent` | Site Data Storage | On Application Exit |
| --- | --- | --- | --- |
| In-memory | `false` | Memory only (no folder) | Discarded |
| Persistent | `true` | Folder on disk | Restored on next launch |

A View keeps its assigned session alive, so you don't need to store the `RefPtr<Session>`.

### Creating an In-Memory Session

To create a session that stores all site data in memory, pass `false` for `is_persistent`.

```cpp
///
/// A private session: nothing it stores is written to disk.
///
RefPtr<Session> incognito = renderer->CreateSession(false, "incognito");
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), incognito);
```

An in-memory session never writes cookies, local storage, or IndexedDB databases to disk. When the session is destroyed or the application exits, all browsing data is discarded.

Use in-memory sessions for private browsing views, guest logins, or kiosk interfaces that must discard state when finished.

### Creating a Persistent Session

To create a session that saves its data to disk, pass `true` for `is_persistent`.

```cpp
///
/// Player two's cookies and storage live apart from the default session.
///
RefPtr<Session> player_two = renderer->CreateSession(true, "player-2");
RefPtr<View> view = renderer->CreateView(800, 600, ViewConfig(), player_two);
```

Persistent sessions write browsing data to disk under the session name. Creating a persistent session with the same name on the next launch reloads that data, restoring saved logins and settings.

Use persistent sessions to give individual users or players their own isolated profiles alongside the default session.

## Configuring the Storage Path

To set the base directory where persistent sessions write their data, configure `Config::cache_path` before creating the renderer.

```cpp
void Init() {
  InitPlatform();

  Config config;
  config.cache_path = "./ultralight_cache/";
  Platform::instance().set_config(config);

  ///
  /// The default session writes to ./ultralight_cache/default/ and a
  /// "player-2" session to ./ultralight_cache/player-2/.
  ///
  renderer = Renderer::Create();
}
```

Each persistent session writes to a subfolder inside `Config::cache_path` matching the session name. You should set this path to a writable, per-user folder (see [Creating the Renderer](/docs/2.0/creating-the-renderer#content-configuring-the-library)).

Call `Session::disk_path()` to inspect the folder where a persistent session writes its data. This returns `Config::cache_path` joined with the session name (relative when `Config::cache_path` is relative). This path is meaningful only for persistent sessions.

> 🚧 Set Cache Path Explicitly
>
> If you leave `Config::cache_path` empty, the renderer creates the `default` directory relative to the current working directory of the process. Site data lands wherever the application was launched from.

## Sharing Sessions

You can share browsing data across multiple Views by assigning them the same session.

### Sharing Between Views

To share browsing data, pass the same `Session` to each `Renderer::CreateView()` call:

```cpp
RefPtr<View> lobby_view;
RefPtr<View> shop_view;

void CreatePlayerTwoViews() {
  RefPtr<Session> player_two = renderer->CreateSession(true, "player-2");

  ///
  /// Both Views share player two's cookies and storage.
  ///
  lobby_view = renderer->CreateView(800, 600, ViewConfig(), player_two);
  shop_view = renderer->CreateView(800, 600, ViewConfig(), player_two);
}
```

Views on the same session share cookies, local storage, IndexedDB databases, and cached resources— logging in on one View logs in to all other Views on that session.

Each View keeps its own session storage and back/forward history.

Views assigned to differently named sessions keep their data isolated.

### Reusing Persistent Session Names

Two persistent sessions created with the same name share one disk folder and its stored data. The library does not check whether session names are unique.

In-memory sessions never share data. Separate in-memory sessions remain isolated from each other, and an in-memory session never reads a persistent session's data, even if both use the same name.

> 🚧 Use Unique Session Names
>
> Give each persistent session its own name unless sharing data is intentional. Persistent sessions with the same name share their data live while the application runs and reload it across launches.