Skip to main content

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 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, 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, and Codex
  • 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, topic, and date range.

​
Set up Sessions

Enforce hooks block shadow MCPs as soon as they’re installed. The workspace Full session scanning toggle is what makes detailed prompts, reasoning, tool calls, and scanner results appear in Sessions.
1

Enable Full session scanning

Go to Settings → Workspace → Full session scanning.Turn on Full session scanning APIs, then enable the clients you want to monitor, such as Cursor, Claude Code, Codex, Runlayer Agents, or the TypeScript SDK.
2

Install client hooks

Install hooks per Enforce. For Sessions, pass --all-events so the hooks send full session telemetry, not just shadow MCP enforcement.
3

Configure scanners

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

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. Enforce is the canonical guide for installing hooks (supported clients, CLI, flags, MDM). For Sessions specifically:
  • Install with --all-events so hooks send full session telemetry
  • Enable the matching client under Settings → Workspace → Full session scanning

​
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

Check:
  • Full session scanning APIs is enabled in Settings → Workspace
  • The client is enabled under Full session scanning
  • Hooks were installed with --all-events
  • The AI client was restarted after hooks were installed
  • 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. Enable Full session scanning APIs, enable the client, then reinstall hooks with: 
runlayer setup hooks --install --all-events --yes

​
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, and Codex

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