Audit Logs

Viewing Audit Logs

Every action in Runlayer is logged for security and compliance:

Navigate to Audit Logs in the sidebar
Filter by:
- Date range
- Action type (created, deleted, accessed, etc.)
- User
- Resource (specific MCP server)
- Plugin (plugin lifecycle and plugin-proxied tool calls)
- Client (MCP client application, e.g. Cursor, Claude Desktop)
- Correlation ID
- Request ID
Click on any log entry to see full details

What Gets Logged

MCP server creation, configuration, and deletion
Skill creation, update, and deletion
Plugin creation, update, and deletion
Access requests and approvals
Policy changes
User authentication events
Tool calls and API requests (including skill and plugin proxy calls) — tool call events include ToolGuard scan metadata (scanner name, score, duration) when security scanners are active
Agent run lifecycle (start, success, failure) — including source, model, and duration
Agent artifact lifecycle (creation, update, deletion)
Agent account lifecycle (creation, credential rotation, deletion)
OAuth token refresh events (upstream success/failure, client-side failures)
Managed Slack app creation, completed installation, disconnection, deletion, and successful collaborator grants. Creation, automatic-install, and Slack-side deletion failures include sanitized error codes. An OAuth install link alone is not a completed installation.
Security violations and risk assessments

All logs are tamper-proof and retained for compliance purposes.

Prompts and model reasoning are not part of audit logs. They are captured in Sessions, which are short-term operational monitoring data built from client hooks and agent telemetry. Audit Logs remain the long-term system of record for tool calls, policy decisions, security events, and administrative activity.

Need to query or bulk-export audit logs programmatically? Use the Runlayer MCP audit log tools — including export_audit_logs for JSON/CSV exports with no 90-day hot-window restriction.

Who requested, who acted

Every tool call through Runlayer records the identity that made it and, where it applies, the person and credential behind it. Some fields come from the credential Runlayer verified; others are reported by the calling client and are useful for correlation, not as proof.

Question	Field	Where the value comes from
Who made the call	`actor_type`, `actor_id` (`user` or `agent`)	Verified: the token or API key on the request
Which person an agent acted for	`delegator_user_id`	Verified: the user named in the on-behalf-of token. Empty for machine-to-machine calls
Whose connector credential was used downstream	`credential_mode` (`own`, `obo_grant`, `owner_grant`), `session_grantor_user_id`, `session_grant_id`, `upstream_account_id`	Verified: resolved by Runlayer from the stored grant or account. Empty for connectors without a Runlayer-managed credential
Which Runlayer-hosted agent and run	`agent_id`, `run_id`	Resolved by Runlayer. `run_id` is set only when the session id names a run that belongs to the calling agent account
Which conversation or run in the client	`session_id`, `external_session_id`	Client-supplied: the `x-runlayer-session-id` header (see Agent Platforms)
Which client	`client_name`, `client_version`	Client-supplied: parsed from the `User-Agent` header

How a Runlayer-hosted agent run started is recorded on its agent_run event: source is schedule, webhook, slack, rest, mcp and so on. The actor is the person who started the run or owns its schedule or trigger, or the agent’s own account when the run executes as the agent with no person behind it. For an agent on another platform, Runlayer sees only what reaches it: the agent account and, with an on-behalf-of token, the user your application mapped the caller to. Whether a run was scheduled or asked for by a person, and which agent launched another, is known to that platform. Send it as x-runlayer-session-id or mint a separate agent account per agent if you need it in Runlayer.

Retention

Audit logs are retained in two tiers:

Hot window (90 days by default) — recent events live in the database and power the in-app viewer, filters, and CLI queries.
S3 archive — events older than the hot window are archived to S3 rather than deleted, and remain available through the Runlayer MCP export_audit_logs tool, which is not subject to the hot-window restriction.

On self-hosted deployments the hot window is configurable via the audit_log_archive_hot_window_days Terraform variable (default 90). For retention fully under your own control, enable SIEM Export — every event is delivered to S3 in near real-time, and you set the lifecycle policy on the destination.

Sensitive Connector Redaction

Connectors that handle highly sensitive data (e.g. HR systems, financial databases) can be marked as sensitive by a Super Admin. When enabled, tool call arguments, results, errors, and security scan details are redacted from that connector’s audit log entries for everyone without a viewer role. Sensitivity is set per connector: every call through it is redacted, whether a person or an agent made it.

Enabling sensitive mode

Open Manage connectors → [connector] → Settings. When you add a new connector, the same toggle is under Show advanced settings.
Turn on Sensitive Connector. Only Super Admins see this toggle: it needs the Manage audit log redaction capability, which no other built-in role has.
Optionally pick the roles that can still see unredacted entries for this connector.
Click Save changes. Redaction applies right away, to existing entries as well as new ones.

You can also set it with the Runlayer MCP create_server and update_server tools (sensitive_audit_log, sensitive_audit_log_viewer_role_ids). The same Super Admin check applies.

What gets redacted

Event type	Redacted fields
Tool calls and resource access	`args`, `result`, `error`
Security violations and warnings	`scan_input`, `area_of_concern`, `detected_items`

Metadata such as tool name, server name, timestamps, and actor information remain visible so admins can still see who called what and when — just not the payload contents.

Redaction is applied at read time, not at write time. The underlying audit log data is unchanged. If you later disable sensitive mode or add a viewer role, previously redacted entries become visible again.

Where redaction applies

Because redaction happens when an entry is read, it covers the places people read audit logs inside Runlayer, and not the copies Runlayer delivers to you:

Where	Redacted for users without a viewer role?
Audit log viewer, entry details, and the tool-result download	Yes. The download is refused.
CSV/JSON export, CLI (`uvx runlayer logs`), Runlayer MCP `list_audit_logs`, `get_audit_log`, `export_audit_logs`	Yes
Detection evidence	Yes
SIEM Export (S3)	No. Every event is delivered with its full `details`, including arguments and results.
Session SIEM export	No. Session content is exported unredacted.

So the sensitive setting does not keep payloads out of your SIEM bucket. Treat access to the destination bucket as the access-control boundary, the same as for session SIEM export.

Querying from the CLI

The uvx runlayer logs command shows audit logs in the terminal. By default, the command shows your own events from the last 24 hours.

uvx runlayer logs

Options

Flag	Description
`--type, -t`	Filter by action type(s). Comma-separated or use shortcuts: `auth`, `tools`, `security`, `servers`, `agents`
`--server-id`	Filter by MCP server UUID
`--agent-id`	Filter by agent account UUID
`--client-name`	Filter by client name in event details
`--user-id`	Filter by user ID (admin only, defaults to self)
`--all`	Show all users’ logs (admin only)
`--start`	Start time (ISO 8601). Default: 24 hours ago
`--end`	End time (ISO 8601). Default: now
`--limit, -n`	Max events to return (default 50, max 2000)
`--json`	Output raw JSON for scripting

Examples

# View security events from the last 24 hours
uvx runlayer logs --type security

# View tool calls for a specific server
uvx runlayer logs --type tools --server-id <uuid>

# View all auth events as JSON
uvx runlayer logs -t auth --json

# View all users' events (admin only)
uvx runlayer logs --all --type tools

# View events in a specific time range
uvx runlayer logs --start 2026-03-20T00:00:00Z --end 2026-03-27T00:00:00Z

When the result set is larger than --limit, the CLI prints a next-page command you can copy-paste to continue paginating.

SIEM Export (S3)

Runlayer can continuously export audit logs to S3 for ingestion into your SIEM (e.g. CrowdStrike NG-SIEM, Splunk, Sentinel). Once enabled, every audit event is written as a gzip-compressed JSON file in near real-time.

How it works

Runlayer supports two S3 delivery patterns:

Runlayer-owned bucket — Runlayer writes audit log objects to an S3 bucket in the AWS account that hosts your Runlayer instance. Your team provides an IAM role ARN, and Runlayer grants that role read/list access so your SIEM pipeline can pull objects from the bucket.
Customer-owned bucket — your team provides a destination S3 bucket and prefix that you control. You grant the Runlayer export role write access to that bucket/prefix, and Runlayer writes audit log objects directly there.

In both patterns, each audit log is enqueued to an internal outbox and asynchronously exported as a .json.gz file. Most SIEMs support S3 as a native log source.

Runlayer does not need to assume a customer-owned IAM role for either pattern. In the Runlayer-owned bucket pattern, your role reads from the Runlayer export bucket. In the customer-owned bucket pattern, the Runlayer export role writes directly to your bucket.

S3 object layout

Objects are written with a Hive-style date partition prefix. The default prefix is audit-logs/:

audit-logs/year=2026/month=04/day=08/<audit_log_id>.json.gz

If a tool call produced a large result payload, it is stored alongside the main event:

audit-logs/year=2026/month=04/day=08/payloads/<audit_log_id>-result.json

For customer-owned bucket delivery, your Runlayer team can configure a custom prefix, such as:

runlayer/audit-logs/year=2026/month=04/day=08/<audit_log_id>.json.gz

Payload schema

Each exported file contains a single JSON object:

{
  "schema_version": 2,
  "audit_log_id": "uuid",
  "timestamp": "2026-04-08T12:00:00+00:00",
  "action_type": "TOOL_CALL_SUCCESS",
  "actor_id": "uuid",
  "actor_type": "user",
  "resource_type": "server",
  "resource_id": "uuid",
  "resource_name": "my-connector",
  "details": { ... }
}

Activity from an agent account is attributed to the agent account, not to a person. When the agent acts on behalf of a user with an OBO token, the same entry also records the delegating user, so one entry names both the agent and the person the work was done for. Tool calls made during runs of Runlayer-hosted agents carry the run reference as well, so an action can be traced to the exact execution. Filter by agent account to see everything a given agent did; the CLI’s --agent-id flag does this.

Getting started

To enable SIEM export for your organization, contact your Runlayer account team. You will need to:

Choose a delivery pattern: Runlayer-owned bucket with pull-based ingestion, or customer-owned bucket with direct delivery.
For Runlayer-owned bucket delivery, provide the IAM role ARN your SIEM pipeline will use to read/list exported objects.
For customer-owned bucket delivery, provide the bucket name and prefix, and grant the Runlayer export role s3:PutObject, s3:AbortMultipartUpload, and s3:PutObjectTagging on that prefix.
If your bucket uses SSE-KMS, grant the Runlayer export role the required KMS permissions for writes.

The S3 export is independent of the in-app audit log viewer and the CSV/JSON download export. All three can be used simultaneously.

CrowdStrike NG-SIEM, Splunk, and most major SIEMs support S3 as a native data source. Use your SIEM’s S3 connector and point it at the bucket to start ingesting Runlayer audit events.

Scope and destinations

Audit-log SIEM export covers audit-log records, including policy decisions. Session content uses the separate, opt-in session SIEM export.
S3 is the delivery mechanism. There is no direct Runlayer-to-Datadog (or other SIEM) integration; any SIEM that can ingest logs from S3 can consume the export. The Datadog MCP connector available in Runlayer is for proxying Datadog tool calls through the gateway — it is not a log export destination.

Sessions

Monitor agent activity in real time

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Viewing Audit Logs

What Gets Logged

Who requested, who acted

Retention

Sensitive Connector Redaction

Enabling sensitive mode

What gets redacted

Where redaction applies

Querying from the CLI

Options

Examples

SIEM Export (S3)

How it works

S3 object layout

Payload schema

Getting started

Scope and destinations

Sessions

​Viewing Audit Logs

​What Gets Logged

​Who requested, who acted

​Retention

​Sensitive Connector Redaction

​Enabling sensitive mode

​What gets redacted

​Where redaction applies

​Querying from the CLI

​Options

​Examples

​SIEM Export (S3)

​How it works

​S3 object layout

​Payload schema

​Getting started

​Scope and destinations

​Related Resources

Sessions

Viewing Audit Logs

What Gets Logged

Who requested, who acted

Retention

Sensitive Connector Redaction

Enabling sensitive mode

What gets redacted

Where redaction applies

Querying from the CLI

Options

Examples

SIEM Export (S3)

How it works

S3 object layout

Payload schema

Getting started

Scope and destinations

Related Resources