Skip to content

Runtime Sessions

Preloop uses runtime sessions to represent concrete periods of activity from a managed runtime.

This concept matters because an enrolled agent is not the same thing as one active session.

Managed Agent vs Runtime Session

Preloop separates durable runtime ownership from individual activity windows.

  • A managed agent is the durable identity for an enrolled desktop or CLI runtime
  • A runtime session is the per-session record for active or completed activity

One managed agent can accumulate many runtime sessions over time.

This separation helps Preloop answer two different questions:

  • Which runtime is this?
  • What happened during this session?

Why Runtime Sessions Exist

Runtime sessions give operators a shared way to inspect and correlate activity across flows and externally enrolled agents.

They are useful for:

  • Browsing recent managed activity
  • Tracking whether a runtime is currently active
  • Correlating tool calls and model traffic
  • Supporting operator actions such as ending a session
  • Providing a stable way to explore one session timeline without flattening everything into flow executions only

Key Runtime Session Fields

The exact data model may evolve, but these fields represent the main ideas:

  • session_source_type — where the session came from
  • session_source_id — the source-specific identity for that session
  • session_reference — a human-meaningful or runtime-native reference when available
  • runtime_principal_type — the durable owner type, such as a managed agent
  • runtime_principal_id — the durable owner identifier
  • runtime_principal_name — a readable label for the owner
  • started_at / last_activity_at / ended_at — lifecycle timing

Relationship to Flows

Flow executions and runtime sessions are related, but they are not interchangeable.

A flow execution describes one automation run. A runtime session describes one broader unit of runtime activity.

For flow-backed activity, session data makes it possible to:

  • connect model traffic to a broader runtime identity
  • inspect execution-scoped gateway events together with session-level usage
  • browse multiple sessions without treating flow_execution as the only long-term runtime identity

Relationship to Managed Agents

For enrolled external agents such as OpenClaw:

  • the managed agent is the durable identity
  • each launch or activity window can create or update a runtime session

That means operators can look at:

  • all sessions for one enrolled runtime
  • recent activity for the current session
  • historical model usage and tool activity across sessions owned by the same principal

What You Can See in Session Views

Depending on the product surface, runtime sessions can expose:

  • recent model usage
  • captured gateway interactions
  • last activity time
  • current active/ended state
  • related audit events
  • related managed-agent identity

Operator Actions

Runtime sessions are also useful control-plane objects.

For example, operators can explicitly end a managed session. This updates session state and helps keep console and audit surfaces aligned with the actual runtime lifecycle.

Relationship to the Usage Ledger

Model gateway requests can be attributed back to a runtime session. This means the same shared usage data can be sliced by:

  • account
  • flow
  • model
  • runtime principal
  • runtime session

That shared attribution model is what makes dashboard telemetry, runtime session explorers, and per-model observability work together.

Where to Explore It Next