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, 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, 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 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

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, 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.
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 Deploy AI Watch 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 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 agents, the Hooks SDK (TypeScript or Python) sends the same lifecycle and tool events through the hook pipeline.
Enforce is the guide for supported hook clients and manual hook flags. Deploy AI Watch 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.
Use Set up Sessions above as the checklist for Full session scanning, Hook clients, and event hook installation. Use Deploy AI Watch 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. 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).
  3. Use Alert mode before Block mode for new tool scanners and AgentGuard. Alert mode logs detections without blocking, so you can tune sensitivity on real traffic before enforcing.
  4. Roll out policies gradually — start with deny-all and grant exceptions as legitimate usage patterns emerge.
  5. Verify 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 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 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.

​
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 package flag is unset or true (see Deploy AI Watch), 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 Deploy AI Watch.

​
AgentGuard options are missing

See AgentGuard → Requirements.

Enforce

Install hooks for Cursor, VS Code, Claude Code, GitHub Copilot CLI, Codex, Hermes, and Goose

ToolGuard Models

Configure per-call tool scanners and model sensitivity

AgentGuard

Session-level behavior monitoring across the agent trajectory

Policies

Restrict tools using access policies

Claude Cowork monitoring

Send Cowork session events via OTLP