- 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, hint, 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, Gemini CLI, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, Hermes, Goose, Windsurf, and the Runlayer browser extension
- Anthropic Inference hooks send governed Claude.ai and Claude Code transcripts from Anthropic’s infrastructure before inference; see Anthropic Inference hooks
- Native runtime hooks send hosted Vercel Eve lifecycle events without an external relay
- OTLP telemetry sends Claude Code and Claude Cowork session events as OTLP logs (see Claude Code OTLP monitoring and Claude Cowork monitoring; Cowork exports directly from Anthropic’s infrastructure) and Glean session events as OTLP traces (where enabled for your tenant). Runlayer accepts the OTLP metrics signal but doesn’t store it
- 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
- Identity — user, client, status, timestamps, and source
- Prompt context — initial prompt and topic when available
- Timeline — prompts, thoughts, responses, tool inputs, tool outputs, tool permission prompts (allow/deny decisions), 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
Set up Sessions
1
Enable Full session scanning
Go to Settings → Agent session monitoring.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, confirm each client or source you want to record in Sessions is enabled, such as Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, Hermes, Goose, Windsurf, the Runlayer browser extension, Vercel Eve, Claude Cowork, Runlayer Agents, or the Hooks TypeScript SDK. Newly supported clients such as Vercel Eve are enabled by default.Disable a client if you do not want its prompts, reasoning, tool inputs, and tool outputs collected.Runlayer agent runs are recorded only while both Full session scanning APIs and Runlayer Agents are on. These switches also decide what reaches a session SIEM export.
3
Install client hooks or configure OTLP
For IDE or CLI clients, install or reinstall hooks. For Sessions, pass For managed deployments, set Sessions in Deploy AI Watch. Installer startup is fail-closed with no hooks; after settings sync,
--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.Sessions=true installs the full session hook set. Protect or Enforce with Sessions off installs decision hooks without full session telemetry.For Claude Cowork, configure OTLP monitoring to send session events. See Claude Cowork monitoring for setup.Claude Code can also send session events over OTLP. Prefer hooks where they can run, because OTLP is observe-only. See Claude Code OTLP monitoring for setup.For organization-wide Claude prompt inspection, configure Anthropic
Inference hooks. This server-side integration
can enforce input scanner verdicts and publish supported transcripts into
Sessions without a device-installed hook.For Vercel Eve, install the native Runlayer runtime hook and add the active
Eve session ID to Runlayer MCP headers. See Vercel Eve setup.4
Configure scanners
Under Settings → Security Scanners, tune catalog and per-call tool scanners, then configure AgentGuard and Block later tool calls when any scanner blocks.
5
Review activity
Open Sessions in the sidebar. Start with the Flagged 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 and supported hosted-runtime 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. Vercel Eve uses a native runtime hook. For other 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.Tool permission prompts
When a coding agent asks the user to approve a tool call — for example Claude Code’s allow/deny permission prompt, a CodexPermissionRequest, or a Cursor permission decision — Runlayer captures that prompt through the hook pipeline (the PreToolUse, PermissionRequest, and PostToolUse events). Each captured permission event records the tool name, the tool input, and the resulting decision (allow or deny) and decision source (the user, an agent auto-approval, or a client setting).
These appear on the session timeline alongside Runlayer’s own scanner outcomes (pass, alert, hint, mask, block). This lets reviewers distinguish the agent’s native allow/deny prompts from Runlayer’s policy and scanner enforcement on the same tool call — for example, seeing that a developer approved a shell command that a Runlayer tool scanner then flagged.
Permission-prompt capture requires Full session scanning and the client’s hooks installed in event mode (see Set up Sessions). It relies on the client actually emitting a permission event: web chat brought in through compliance imports (Claude web/desktop, ChatGPT web) is monitor-only and does not include native permission prompts.
Reviewing Sessions
The Sessions page groups activity into security-focused tabs:- All shows every session visible to you.
- Flagged shows sessions where scanners or policies recorded warning-level activity (Alert or Hint).
- Blocked shows sessions where Runlayer blocked an action.
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 Block later tool calls when any scanner blocks 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 polls the provider’s compliance API on a schedule and imports supported chat sessions into the Sessions view. Runlayer currently supports the Anthropic Compliance API (Claude web and desktop chat) and the OpenAI Compliance Logs Platform (ChatGPT web chat). 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
Set up compliance imports
Compliance API access is an enterprise plan capability on the provider side, and the compliance API key is issued by an admin of your Anthropic or OpenAI organization — not by Runlayer. If your org does not yet have compliance API access, request it from the provider first (OpenAI’s Compliance Logs Platform is granted on request and can take a few days to enable). Configure providers in Settings → Agent session monitoring. Runlayer stores the API key encrypted at rest, and imports are scoped to your organization.- Anthropic (Claude)
- OpenAI (ChatGPT)
- In claude.ai, the primary owner of your Claude Enterprise organization opens Organization settings → API and creates a Compliance Access Key (
sk-ant-api01-…) with theread:compliance_user_datascope. An organization owner can create a key limited to their own organization. Admin API keys from the Claude Console only reach Anthropic’s Activity Feed and cannot import chats. - In Runlayer, open Settings → Agent session monitoring, expand Claude.ai Web under Web clients, and paste the key into Compliance Access Key.
- Turn on the Claude.ai Web toggle and save.
org_… form) to limit the import to those organizations.Claude Science, Claude for Microsoft 365, and Claude in Chrome (beta): with the same key, Runlayer can also import prompts and replies from these apps, which Runlayer hooks don’t capture. Claude Code and Cowork sessions aren’t imported this way, because Runlayer hooks already capture them. To limit these imports by organization, use the UUID form of each organization ID. This import is in beta. Contact your Runlayer account team to enable it.
Who a compliance import covers
A compliance import covers every user in the connected Anthropic organization or OpenAI workspace. It doesn’t depend on Runlayer sign-in, SSO or directory sync groups, or AI Watch:- Chats from people who have a Runlayer account (same email) are filed under that account.
- Chats from people who have never signed in to Runlayer are still imported and stored, under the provider’s user ID.
- The only scope control is the list of organization or workspace IDs. There is no per-user or per-group filter.
Anthropic Inference hooks work differently: a live prompt is only accepted when its email matches an active Runlayer user. See Anthropic Inference hooks.
Privacy and access
Sessions can contain prompts, reasoning, tool inputs, and tool outputs. Treat them as sensitive operational data. With Session privacy on (Settings → Agent session monitoring), other users’ sessions are redacted by default: the list shows a topic or session ID instead of raw prompts, and the first prompt, generated title and page URL are withheld, in the API and the Runlayer MCPlist_sessions tool too. The timeline keeps each event’s time, type, tool name, model and token counts, with ***REDACTED*** in place of every prompt, response, tool input and output, and page URL. People with the View unredacted content capability see it blurred until they unredact it; everyone else sees a notice instead. The API and the Runlayer MCP get_session tool return the same placeholder timeline. Safety charts and alerts stay visible. For who can see an agent’s runs, see Who can see an agent’s runs.
To decide per person who reads other people’s content, with policies, break-glass access and protected sessions, see Session content access.
Excluding users or groups from session capture
Some teams cannot send certain users’ activity to Runlayer at all — executives, legal, or anyone working on material that is not yet public inside the company (M&A, restructuring, unannounced plans). This is a common requirement when moving a POC toward production, and it is handled at the source: session capture is opt-in per device, so a device that is not configured to send session telemetry never transmits prompts or reasoning to Runlayer in the first place. There is nothing to filter server-side because the excluded user’s content never leaves the endpoint. One nuance to decide up front: enforcement is not free of transmission. Blocking a shadow MCP requires sending each tool call to Runlayer for policy evaluation, so a device running enforcement hooks still transmits tool inputs and outputs (and those events are stored when the client is enabled for the workspace) even withSessions disabled. If a group requires that nothing be transmitted, do not deploy the AI Watch package to that group at all.
Scope capture by targeting the AI Watch / hook configuration to MDM device groups rather than enabling it org-wide:
- Split your deployment into device groups and assign a distinct Runlayer MDM configuration per group. Enable Sessions only for groups you intend to monitor. See Deploy AI Watch for per-group targeting.
- Claude Cowork cannot be scoped by device. Cowork monitoring is configured org-wide in Claude admin settings and exports from Anthropic’s VM, not from managed devices, so MDM targeting does not apply. To exclude users from Cowork capture, keep them in a separate Claude organization that has no Runlayer OTLP endpoint configured.
- Enforcement and Sessions stay independent — an excluded group can keep enforcement hooks that block unmanaged shadow MCPs without sending prompts or reasoning, accepting the tool-call transmission described above. See Set up Sessions for how the two controls differ.
- Check compliance imports too. These are server-side: Runlayer imports web chat for every user in the connected Anthropic organization or OpenAI workspace, regardless of any device configuration or Runlayer sign-in. If excluded users must not appear in Sessions at all, they must sit in a provider organization/workspace that is not covered by a configured compliance import (or the import must be disabled).
Exclusion is device/group-scoped through MDM targeting by default. Where policy rules are enabled, you can instead create a user-scoped policy with Sessions off under Settings → Endpoint configuration. That setting is applied by the device, so it is not a server-side guarantee. As a coarser alternative, some teams keep excluded users on a separate model-provider account entirely so their activity is never in scope for the managed configuration.
SIEM export
Session SIEM export sends prompts, reasoning, tool calls, and scanner verdicts to S3 in near real time. Runlayer writes directly to a bucket that your organization controls. Customer-owned buckets keep retention, encryption, notifications, and SIEM access in your AWS account. Runlayer assumes your IAM role with an external ID for cross-account access. This opt-in export is available for supported AWS deployments. Contact your Runlayer account team to make sure that the export is available. New exports start from new events. The export does not include earlier sessions.The export carries the events Sessions records, so the switches under
Settings → Agent session monitoring also control what reaches your
bucket. Turning off Full session scanning APIs or a client under Hook
clients stops that client’s prompts, responses, and tool calls; tool scan
results (
scan_recorded) can still arrive. Runlayer agent runs need both
Full session scanning APIs and Runlayer Agents turned on. Events from
while a switch was off are not exported later. If your bucket only receives
scan_recorded records, check these switches first.Configure the customer-owned bucket
Runlayer provides these values:- A unique external ID
- The Runlayer AWS principal ARN
- The proposed object prefix, which is
sessions/by default
- The S3 bucket name
- The AWS Region
- The IAM role ARN
- The object prefix (
sessions/by default) - Whether the bucket uses SSE-KMS
sessions prefix with your values.
<prefix>/*), never a narrower path such
as sessions/year=*. Runlayer writes both the NDJSON objects and the
payloads/ full-body objects under the prefix. If a payloads/ write is
denied, export pauses and retries until the policy is fixed; it does not skip
the event.
The same rule applies if your bucket policy grants Runlayer write access
directly, with no customer IAM role: the statement that allows Runlayer’s
principal s3:PutObject must use "Resource": "arn:aws:s3:::<bucket-name>/<prefix>/*".
The customer IAM role needs only s3:PutObject for S3 writes. If the bucket
uses SSE-KMS, grant kms:GenerateDataKey to this role. The KMS key policy must
also allow the role.
S3 object layout
Objects are written with a Hive-style date partition prefix. Each event object is gzip-compressed NDJSON with content typeapplication/x-ndjson and content
encoding gzip. Full-body objects under payloads/ are plain JSON with content
type application/json. The default prefix is sessions/:
data_payload_uri rather than building the key
yourself. The name ends in the SHA-256 of the body, so two events that share
an event_id but carry different bodies (see
Duplicates and retries) never overwrite each other,
and a retried write of the same event lands on the same object.
Ingest the .jsonl.gz objects into your SIEM. Objects under payloads/ hold
the full content of large events; see Truncated content.
If S3 event notifications drive your ingestion (for example a Splunk SQS-based
S3 input, the Microsoft Sentinel S3 connector, the Datadog Forwarder, or an
EventBridge rule), filter them on the .jsonl.gz suffix or on the
<prefix>/year= prefix. A filter on <prefix>/ alone also matches the
payloads/ objects, which are plain JSON of up to about 1 MB each, not event
lines. Fetch those through data_payload_uri when you need the full body.
Treat object names as opaque unique identifiers. The date partition is each
event’s UTC arrival date, which can differ from the event’s own
timestamp — scan by partition for completeness, filter by timestamp for
analysis.
Payload schema v1
Each NDJSON line is one schema-v1 event. The stable top-level field names are:
Top-level field names and meanings remain stable within schema v1.
data
normally contains the raw producer body and can evolve additively as producers
add fields. Truncation can replace data with a preview or an empty object. In
extreme cases, enforcing the event-size cap can also null or omit lower-priority
top-level fields. For the values of event_category and event_type, see
Event types.
Event types
Each event has three type fields:event_categoryis the broad group, for exampletool.event_typeis the normalized event, for examplepre_tool_use.raw_event_nameis the name the producer sent. It is producer-specific and is not normalized. For example, Claude Code sendsPreToolUseand Cursor sendspreToolUse; both becometool/pre_tool_use.
event_category and event_type for SIEM rules. Use client and
raw_event_name only for client-specific logic.
The list below can grow. New clients and producers can add values in schema v1
without notice. SIEM consumers must accept unknown values of
event_category, event_type, and raw_event_name. Runlayer does not store or
export a raw client event that it cannot map. It does not send such an event
with a placeholder category.
Not every client sends every event type. The Sources column gives examples,
not a complete list. “Claude Code-format clients” means Claude Code and the
clients that use its hook format, such as GitHub Copilot CLI, Gemini CLI,
Cline, Devin CLI, Grok CLI, Windsurf, Claude Cowork, and Glean.
The same
event_type can occur in more than one category. For example,
turn_completed occurs in control and in artifact. Always match on the pair.
This example shows a Claude Code MCP tool call. The values are synthetic.
Duplicates and retries
Delivery is at-least-once: a retry can write the same event again, as a duplicate line or in a second object. SIEM consumers must dedupe onsession_id, event_id and part_index. All parts of a chunked event share
one event_id; other events always have part_index 0. A retry always repeats
all three values. event_id alone is not unique across sessions: for clients
that send their own event ids, event_id is derived from that id, so two
sessions can carry the same event_id for different events. Keying on
session_id as well keeps both lines, the same way Runlayer keeps both in each
session’s timeline.
Truncated content
The default per-event cap is 256 KiB, with a 4 KiB UTF-8 preview. A preview is stored indata._preview; data._preview_truncated indicates whether the
preview itself was cut.
Content over the cap is not lost. Runlayer writes the full data body to its
own JSON object in the same bucket and prefix, under payloads/, before it
writes the line that points to it. The line’s data_payload_uri field holds
the object’s s3:// URI. Lines under the cap have no data_payload_uri field.
data_original_bytes is not comparable across truncation reasons. For
oversize, it is the serialized size of the whole logical event before content
is shed. For chunked, it is the size of that part only — a fraction of
the logical event. Only a small share of events exceeds the cap at the default
sizes; the rest export with full content.
To rebuild a chunked event, collect the lines with the same chunk_id (parts
can arrive in different objects and on different days), read the object at each
part’s data_payload_uri, join their _chunk strings in part_index order
from 0 to total_parts - 1, and parse the result as JSON. The result is the
event’s original data.
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:- Start with admins and security reviewers. Enable Full session scanning and hooks for a small pilot group before adding broader teams.
- Enable session privacy if your workspace expects user-level confidentiality (see Privacy and access).
- 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.
- Roll out policies gradually — start with deny-all and grant exceptions as legitimate usage patterns emerge.
- Verify agents in the Playground and tighten prompt/tool scope before broad rollout.
- Review blocked and flagged sessions daily during rollout. Use the Flagged and Blocked tabs to triage, and rely on Audit Logs as the long-term record of policy decisions and security events.
- 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.
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 withrunlayer login.
One client’s sessions are missing (e.g. Codex)
If most clients show up but one does not, that client is likely not enabled as a Hook client. Go to Settings → Agent session monitoring → Hook clients and confirm the specific client (Codex, GitHub Copilot CLI, Gemini CLI, Hermes, Goose, and so on) is toggled on. Then reinstall that client’s hooks in event mode and restart it: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 Sessions is enabled in the assigned Runlayer MDM configuration (see Deploy AI Watch), wait for settings sync and the next bootstrap tick, then restart the AI client.Hook commands cannot find runlayer
Install the CLI permanently and restart the AI client:
AgentGuard options are missing
See AgentGuard → Requirements.Related docs
Browser extension
Capture supported AI web chats and apply prompt protection where available
Enforce
Install hooks for Cursor, VS Code, Claude Code, GitHub Copilot CLI, Gemini CLI, Grok CLI, Codex, Qwen Code, Cline CLI, Devin CLI, Muse Code, OpenCode, Hermes, Goose, and Windsurf
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
Claude Code OTLP monitoring
Send Claude Code session events via OTLP