Skip to main content
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, Claude Code session, Codex session, Hermes 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, 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
Sessions are short-term operational monitoring data. Audit Logs remain the long-term system of record for policy decisions, security events, and administrative activity.

​
How Sessions work

Sessions are built from several event sources:
  • Client hooks send AI IDE activity from Cursor, Claude Code, Codex, and Hermes
  • 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

1

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

Choose the clients to monitor

Under Hook clients, enable each client or source you want to record in Sessions, such as Cursor, Claude Code, Codex, Hermes, Claude Cowork, Runlayer Agents, or the TypeScript SDK.Leave a client off if you do not want its prompts, reasoning, tool inputs, and tool outputs collected.
3

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.
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 Enforce → Sessions telemetry; set the Sessions MDM field 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 for setup.
4

Configure scanners

Under Settings → Security Scanners, tune catalog and per-call tool scanners, then configure AgentGuard and the session kill switch.
5

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.

​
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 TypeScript agents, the Runlayer TypeScript SDK sends the same lifecycle and tool events through the hook pipeline.
Enforce is the canonical guide for supported clients, CLI flags, and MDM deployment, but Enforce and Sessions are separate controls. Enforce hooks can block unmanaged Shadow MCPs as soon as they are installed. Full session scanning is what records detailed prompts, reasoning, tool calls, and scanner results in Sessions.
Use Set up Sessions above as the checklist for Full session scanning, Hook clients, and event hook installation. Use Enforce → Sessions telemetry 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 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 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 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:
  1. Start with admins and security reviewers.
  2. Enable session privacy if your workspace expects user-level confidentiality.
  3. Use Alert mode before Block mode for new tool scanners.
  4. Review blocked and alerted sessions daily during rollout.

​
Troubleshooting

​
No sessions appear

Start with 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. For managed deployments, confirm the Sessions MDM field is unset or true (see Enforce → Sessions telemetry), 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: 
uv tool install runlayer
runlayer --help
For managed deployments, use the MDM flow in Enforce.

​
AgentGuard options are missing

See AgentGuard → Requirements.

Enforce

Install hooks for Cursor, Claude Code, Codex, and Hermes

ToolGuard Models

Configure per-call tool scanners and model sensitivity

AgentGuard

Session-level behavior monitoring across the agent trajectory

Security

Monitor security events and violations

Policies

Restrict tools using access policies

Claude Cowork monitoring

Send Cowork session events via OTLP