Sessions

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, Gemini CLI session, Cline CLI session, Codex session, Qwen Code session, Hermes session, Goose session, Windsurf session, Vercel Eve 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, Gemini CLI, Cline CLI, Codex, Qwen Code, 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 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, 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

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

Set up Sessions

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.

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, Cline CLI, Codex, Qwen Code, 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.

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 managed deployments, set Sessions in Deploy AI Watch. Installer startup is fail-closed with no hooks; after settings sync, 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.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.

Configure scanners

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

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

Hook enforcement depth varies by client. Windsurf enforces on pre-tool events only. Runlayer can deny a Windsurf tool call before it runs, but cannot block or rewrite Windsurf tool output. Windsurf tool output is still recorded in the session timeline, and scanner results on that output are observational. 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.

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 Codex PermissionRequest, 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, 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.
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, tool permission prompts, 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 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

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

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 the Anthropic Console, an organization admin issues a Compliance API key (sent as the x-api-key header to https://api.anthropic.com/v1/compliance).
In Runlayer, open Settings → Agent session monitoring and paste the key into Anthropic Compliance API key.
Turn on the Anthropic toggle and save.

Runlayer enumerates your Anthropic organizations and users through the Compliance API and imports their Claude chats. Providing organization IDs is optional — leave the external ID list empty to import across all organizations the key can see.

Request access to the Compliance Logs Platform from OpenAI for your enterprise workspace or organization, then have an admin issue a compliance API key (sent as a Bearer token to https://api.chatgpt.com/v1/compliance).
In Runlayer, open Settings → Agent session monitoring and paste the key into OpenAI Compliance API key.
Add at least one workspace or organization ID. A value that starts with org- is treated as an organization scope; any other value is treated as a workspace scope.
Turn on the OpenAI toggle and save.

OpenAI requires at least one workspace or organization ID and an API key before the provider can be enabled — the toggle stays disabled until both are set.

After a provider is enabled, imported web chats appear in Sessions on the next sync cycle, tagged with their source and a provider link when one is available. Changing the API key or external IDs resets the sync cursor, so the next run re-imports from the provider’s current window.

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.

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 with Sessions 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:

Group	AI Watch / client config	Result
Recorded (e.g. engineering)	Synced `Sessions` setting enabled (event-mode hooks installed)	Full session telemetry flows to Sessions
Excluded, enforcement kept (e.g. legal)	Synced `Sessions` setting disabled; Mode Protect or Enforce	No prompts or reasoning are sent or stored; enforcement hooks still transmit tool calls for policy evaluation
Excluded, zero transmission (e.g. executives)	No AI Watch package deployed	Nothing is sent from the device (see step 4 for server-side imports)

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. 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 today is device/group-scoped through MDM targeting, not a per-user toggle inside the Runlayer app — centralized per-user exclusion levers are on the roadmap. 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.

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

Provide these values to Runlayer:

The S3 bucket name
The AWS Region
The IAM role ARN
The object prefix (sessions/ by default)
Whether the bucket uses SSE-KMS

Use this trust policy for the customer IAM role. Replace the placeholders with the values from Runlayer.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunlayerSessionSiemExportTrust",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<runlayer-principal-arn>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<external-id-from-runlayer>"
        }
      }
    }
  ]
}

Attach this write policy to the customer IAM role. Replace the bucket name and sessions prefix with your values.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RunlayerSessionSiemExportWrite",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<bucket-name>/sessions/*"
    }
  ]
}

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 object is gzip-compressed NDJSON with content type application/x-ndjson and content encoding gzip. The default prefix is sessions/:

sessions/year=YYYY/month=MM/day=DD/<object>.jsonl.gz

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:

Field group	Fields
Schema and time	`schema_version`, `arrival_at`, `timestamp`
Event, actor, session, and chunk identity	`organization_id`, `event_id`, `actor_id`, `actor_type`, `session_id`, `external_session_id`, `chunk_id`, `part_index`, `total_parts`
Actor details	`actor_email`, `actor_display_name`, `actor_workos_id`, `actor_workos_directory_user_id`
Event metadata	`client`, `event_category`, `event_type`, `raw_event_name`, `blocked`, `block_reason`, `duration_ms`
Producer metadata	`tool_name`, `server_slug`, `internal_type`, `agent_id`, `source`, `model`, `monitor_only`
Content and truncation	`data`, `data_truncated`, `data_original_bytes`

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.

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 on event_id.

Truncated content

The default per-event cap is 256 KiB, with a 4 KiB UTF-8 preview. A preview is stored in data._preview; data._preview_truncated indicates whether the preview itself was cut.

`data_truncated`	Meaning
`oversize`	The event exceeded the size cap. `data` contains a bounded preview.
`chunked`	A very large event was split during ingestion. The first part supplies the preview and tool attribution; later parts are not exported.
`invalid`	The producer sent a non-object `data` value. It was dropped, not truncated, and `data` never contains a preview. `data_original_bytes` can be null.

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 the first 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.

Session SIEM export contains unredacted content. The workspace’s Session privacy setting and a connector’s Sensitive audit log setting do not apply to exported session content. Access to the destination bucket is the access-control boundary.

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

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:

runlayer setup hooks --client codex --install --event-hooks --yes

Each client only reads its hook config at process start, so the client must be fully restarted after the toggle is enabled or hooks are reinstalled.

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:

uv tool install runlayer
runlayer --help

For managed deployments, use Deploy AI Watch.

AgentGuard options are missing

See AgentGuard → Requirements.

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, Cline CLI, Codex, Qwen Code, 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

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

How Sessions work

Set up Sessions

Hook integrations

Tool permission prompts

Reviewing Sessions

AgentGuard

Session policies

Web chat and compliance imports

Set up compliance imports

Privacy and access

Excluding users or groups from session capture

SIEM export

Configure the customer-owned bucket

S3 object layout

Payload schema v1

Duplicates and retries

Truncated content

Recommended rollout

Troubleshooting

No sessions appear

One client’s sessions are missing (e.g. Codex)

Enforce blocks shadow MCPs, but Sessions are empty

Hook commands cannot find `runlayer`

AgentGuard options are missing

Browser extension

Enforce

ToolGuard Models

AgentGuard

Policies

Claude Cowork monitoring

​How Sessions work

​Set up Sessions

​Hook integrations

​Tool permission prompts

​Reviewing Sessions

​AgentGuard

​Session policies

​Web chat and compliance imports

​Set up compliance imports

​Privacy and access

​Excluding users or groups from session capture

​SIEM export

​Configure the customer-owned bucket

​S3 object layout

​Payload schema v1

​Duplicates and retries

​Truncated content

​Recommended rollout

​Troubleshooting

​No sessions appear

​One client’s sessions are missing (e.g. Codex)

​Enforce blocks shadow MCPs, but Sessions are empty

​Hook commands cannot find runlayer

​AgentGuard options are missing

​Related docs

Browser extension

Enforce

ToolGuard Models

AgentGuard

Policies

Claude Cowork monitoring

How Sessions work

Set up Sessions

Hook integrations

Tool permission prompts

Reviewing Sessions

AgentGuard

Session policies

Web chat and compliance imports

Set up compliance imports

Privacy and access

Excluding users or groups from session capture

SIEM export

Configure the customer-owned bucket

S3 object layout

Payload schema v1

Duplicates and retries

Truncated content

Recommended rollout

Troubleshooting

No sessions appear

One client’s sessions are missing (e.g. Codex)

Enforce blocks shadow MCPs, but Sessions are empty

Hook commands cannot find `runlayer`

AgentGuard options are missing

Related docs