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

# Sessions

> Monitor, detect, and enforce security across the full agentic lifecycle

Sessions monitor and secure the entire agentic lifecycle — every prompt, reasoning step, tool call, and response across AI IDEs, agents, and web chat tools. Security and platform teams use Sessions to see what agents are doing in real time, detect risky behavior across multiple steps, and enforce controls before a compromised or misaligned agent can continue.

A session represents one AI conversation or run, such as a Cursor chat, VS Code session, Claude Code session, GitHub Copilot CLI session, Codex session, Hermes session, Goose session, Runlayer Agent run, or imported web chat.

Use Sessions to:

* Review prompts, reasoning, all tool calls (MCP and local), and model responses in one timeline
* See tool scanner outcomes for each tool call, including pass, alert, mask, and block decisions
* Detect unsafe agent trajectory with [AgentGuard](/agentguard), including prompt injection, reasoning drift, and multi-step manipulation
* Enforce tool scanner and AgentGuard decisions across the rest of the session
* Apply session policies for data isolation and protection against session-based attacks like privilege drift and cross-context access

<Note>
  Sessions are short-term operational monitoring data. Audit Logs remain the long-term system of record for policy decisions, security events, and administrative activity.
</Note>

## How Sessions work

Sessions are built from several event sources:

* **Client hooks** send AI IDE and CLI activity from Cursor, VS Code, Claude Code, GitHub Copilot CLI, Codex, Hermes, and Goose
* **OTLP telemetry** sends Claude Cowork session events directly from Anthropic's infrastructure
* **Runlayer Agents** stream run activity into the same session model
* **Tool scanners** add scan results for every MCP and local tool call — shell, file, web, and other client-local operations
* **Compliance imports** bring supported web chat activity in for monitor-only review

Runlayer normalizes everything into a single session record. Each session shows:

* **Identity** — user, client, status, timestamps, and source
* **Prompt context** — initial prompt and topic when available
* **Timeline** — prompts, thoughts, responses, tool inputs, tool outputs, errors, and subagent activity
* **Tool usage** — tools called, connected servers, and failures
* **Security results** — tool scanner passes, warnings, alerts, masked content, and blocks
* **AgentGuard turns** — agent trajectory analysis across prompt, reasoning, tool output, and follow-up reasoning
* **External links** — provider links for imported web chat sessions when available

The Sessions page supports filtering by action, status, actor, client, topic, and date range.

## Set up Sessions

<Steps>
  <Step title="Enable Full session scanning">
    Go to **Settings → General → Full session scanning**.

    Turn on **Full session scanning APIs**. This allows Runlayer to accept detailed session events from hooks and first-party agents.
  </Step>

  <Step title="Choose the clients to monitor">
    Under **Hook clients**, enable each client or source you want to record in Sessions, such as Cursor, VS Code, Claude Code, GitHub Copilot CLI, Codex, Hermes, Goose, Claude Cowork, Runlayer Agents, or the Hooks SDK (TypeScript or Python).

    Leave a client off if you do not want its prompts, reasoning, tool inputs, and tool outputs collected.
  </Step>

  <Step title="Install client hooks or configure OTLP">
    For IDE or CLI clients, install or reinstall hooks. For Sessions, pass `--event-hooks` (or the `--all-events` alias) so hooks send full session telemetry, not just shadow MCP enforcement.

    Shadow MCP source blocking can run without full session telemetry. Local tool lifecycle scanning requires **Full session scanning APIs** and the target **Hook client** to be enabled.

    ```bash theme={null}
    runlayer setup hooks --client cursor --install --event-hooks --yes
    ```

    For MDM deployments, the bootstrap installs the full session hook set by default — no script edit needed. See [Deploy AI Watch](/shadow-ai/deploy) for the `Sessions` package flag; set it to `false` only if you want enforcement hooks without session telemetry.

    For Claude Cowork, configure OTLP monitoring to send session events. See [Claude Cowork monitoring](/claude-cowork-monitoring) for setup.
  </Step>

  <Step title="Configure scanners">
    Under **Settings → Security Scanners**, tune catalog and per-call [tool scanners](/runlayer-toolguard), then configure [AgentGuard](/agentguard) and the session kill switch.
  </Step>

  <Step title="Review activity">
    Open **Sessions** in the sidebar. Start with the **Alerted** and **Blocked** filters to triage risky activity, then open a session to inspect the timeline and scanner results.
  </Step>
</Steps>

## Hook integrations

Hooks are the real-time source for IDE sessions. They capture both MCP tool calls and local tool activity, so Sessions show shell commands, file reads and writes, web fetches, and other client-local operations alongside MCP activity. For custom agents, the Hooks SDK ([TypeScript](/runlayer-hooks-typescript-sdk) or [Python](/runlayer-hooks-python-sdk)) sends the same lifecycle and tool events through the hook pipeline.

<Note>
  [Enforce](/shadow-ai/enforce) is the guide for supported hook clients and manual hook flags. [Deploy AI Watch](/shadow-ai/deploy) is the canonical guide for MDM package configuration, including the `Sessions` flag. Enforce and Sessions are separate controls: Enforce hooks can block unmanaged Shadow MCPs as soon as they are installed, while full session scanning records detailed prompts, reasoning, tool calls, and scanner results in Sessions.
</Note>

Use [Set up Sessions](#set-up-sessions) above as the checklist for Full session scanning, Hook clients, and event hook installation. Use [Deploy AI Watch](/shadow-ai/deploy) for managed deployments.

After hook installation or MDM redeployment, restart the AI client so the new hooks load.

## Reviewing Sessions

The Sessions page groups activity into security-focused tabs:

* **All** shows every session visible to you.
* **Alerted** shows sessions where scanners or policies recorded warning-level activity.
* **Blocked** shows sessions where Runlayer blocked an action.

Open a session to inspect the timeline. Depending on the source and workspace privacy settings, the timeline can include prompts, reasoning, local tool calls, MCP tool calls, scanner decisions, and links back to audit logs.

## AgentGuard

[AgentGuard](/agentguard) is Runlayer's session-level behavior monitoring. It looks across the agent's trajectory — prompt, reasoning, tool output, follow-up reasoning — to detect output-steering injection, sudden reasoning pivots, and slow-chain drift that single-call scanners miss.

In the Sessions timeline, AgentGuard results appear as session turns. Configure Agent monitoring and the session kill switch on the [AgentGuard](/agentguard) page.

## Session policies

Session policies enforce data isolation and defend against session-based attacks — privilege drift, cross-context access, and tool calls that switch resources mid-session. They build on [session payload tracking](/platform-policies#session-payload-tracking) and are configured as connector or agent **Policies**.

## Web chat and compliance imports

Some providers expose compliance APIs for reviewing web chat activity. When configured, Runlayer can import supported chat sessions into the Sessions view.

Imported web sessions are **monitor only**:

* They appear in Sessions for review and investigation
* They can include provider links when available
* They do not support real-time blocking because the chat already happened

Use web chat imports for visibility. Use client hooks for real-time monitoring and enforcement.

## Privacy and access

Sessions can contain prompts, reasoning, tool inputs, and tool outputs. Treat them as sensitive operational data.

Workspace settings may redact session content for users who are not allowed to view another user's activity. Admins with the required permission can view unredacted session content when needed for investigation.

## Recommended rollout

Sessions work best when enabled gradually — observe first, then enforce, then expand. The same phased approach applies when moving from a pilot to org-wide deployment:

1. **Start with admins and security reviewers.** Enable Full session scanning and hooks for a small pilot group before adding broader teams.
2. **Enable session privacy** if your workspace expects user-level confidentiality (see [Privacy and access](#privacy-and-access)).
3. **Use Alert mode before Block mode** for new [tool scanners](/runlayer-toolguard) and [AgentGuard](/agentguard). Alert mode logs detections without blocking, so you can tune sensitivity on real traffic before enforcing.
4. **Roll out [policies](/platform-policies) gradually** — start with deny-all and grant exceptions as legitimate usage patterns emerge.
5. **Verify [agents](/platform-agents) in the Playground** and tighten prompt/tool scope before broad rollout.
6. **Review blocked and alerted sessions daily during rollout.** Use the **Alerted** and **Blocked** tabs to triage, and rely on [Audit Logs](/platform-audit-logs) as the long-term record of policy decisions and security events.
7. **Expand client coverage** — once the pilot group's alerts are quiet and scanner settings are tuned, enable additional Hook clients and move to managed [MDM deployment](/shadow-ai/deploy) for the rest of the org.

For the infrastructure side of moving from POC to production (self-hosted deployment, networking, upgrades), see the [deployment overview](/deployment/overview).

## Troubleshooting

### No sessions appear

Start with [Set up Sessions](#set-up-sessions). Empty Sessions usually mean Full session scanning is off, the source is not enabled, hooks were not installed in event mode, or the AI client was not restarted after hook installation or MDM redeployment.

Also check that the user is logged in with `runlayer login`.

### Enforce blocks shadow MCPs, but Sessions are empty

Enforce and Sessions are separate. Shadow MCP blocking can work without full session telemetry.

Complete [Set up Sessions](#set-up-sessions). For managed deployments, confirm the `Sessions` package flag is unset or `true` (see [Deploy AI Watch](/shadow-ai/deploy)), wait for the next bootstrap tick, then restart the AI client.

### Hook commands cannot find `runlayer`

Install the CLI permanently and restart the AI client:

```bash theme={null}
uv tool install runlayer
runlayer --help
```

For managed deployments, use [Deploy AI Watch](/shadow-ai/deploy).

### AgentGuard options are missing

See [AgentGuard → Requirements](/agentguard#requirements).

## Related docs

<CardGroup cols={2}>
  <Card title="Enforce" icon="shield" href="/shadow-ai/enforce">
    Install hooks for Cursor, VS Code, Claude Code, GitHub Copilot CLI, Codex, Hermes, and Goose
  </Card>

  <Card title="ToolGuard Models" icon="brain" href="/runlayer-toolguard">
    Configure per-call tool scanners and model sensitivity
  </Card>

  <Card title="AgentGuard" icon="shield-check" href="/agentguard">
    Session-level behavior monitoring across the agent trajectory
  </Card>

  <Card title="Policies" icon="lock" href="/platform-policies">
    Restrict tools using access policies
  </Card>

  <Card title="Claude Cowork monitoring" icon="chart-line" href="/claude-cowork-monitoring">
    Send Cowork session events via OTLP
  </Card>
</CardGroup>