# Telemio runtime sessions

Runtime sessions are Telemio's common lifecycle model for application processes and distributed clients. They complement normal service, browser, mobile, infrastructure, and agent views rather than replacing them.

Use a runtime session when there is a meaningful thing that starts, does work, can own child work, and eventually stops or expires.

Supported kinds include:

- `service` for a particular service process or deploy incarnation
- `worker` for background consumers and worker processes
- `agent` for coding agents, model orchestrators, and durable agents
- `compute` for VMs, sandboxes, containers, and remote execution environments
- `browser` for browser automation or user/browser sessions that need runtime correlation
- `mobile` for iOS, Android, or React Native application sessions
- `serverless` for Lambda, Functions, edge invocations, or bounded serverless execution
- `desktop` for Electron, Tauri, and native desktop sessions
- `cli` for CLI executions that need lifecycle correlation
- `workflow` and `job` for durable workflows, scheduled work, and bounded jobs

## Trusted services

Trusted servers create a runtime session with an ingest/write credential. The API returns a short-lived `tmio_rt_...` ingest token, runtime ID, resource attributes, and a direct console URL.

```text
POST https://api.telemio.sh/v1/runtime-sessions
Authorization: Bearer $TELEMIO_API_KEY
```

Example request:

```json
{
  "kind": "worker",
  "provider": "checkout-platform",
  "externalId": "job_123",
  "externalUrl": "https://example.internal/jobs/job_123",
  "serviceName": "checkout-worker",
  "environment": "production",
  "release": "2026.11.2"
}
```

The response includes:

```json
{
  "id": "rt_...",
  "ingestToken": "tmio_rt_...",
  "consoleUrl": "https://console.telemio.sh/runtimes/rt_...",
  "otlpEndpoint": "https://api.telemio.sh"
}
```

Use the runtime token for telemetry emitted by that runtime. Do not reuse it for unrelated runtimes.

## Browser, mobile, and desktop clients

Distributed applications must not contain privileged Telemio server credentials. Create a client-safe ingest key in the Telemio console and bind it to the application's allowed origin, native app identifier, or website.

A client-safe key can create only `browser`, `mobile`, or `desktop` runtime sessions. Telemio then returns a bounded short-lived runtime token scoped to that runtime and to the signals allowed by the client key.

This makes the client-safe credential the bootstrap identity and the `tmio_rt_...` token the per-session ingest identity.

## Parent and child runtimes

If one runtime starts another, create the child using the parent runtime token or pass `parentRuntimeId` from a trusted service.

Example topology:

```text
Ephemeral compute runtime
└── Agent runtime
    ├── Browser automation runtime
    └── Child agent runtime
```

Preserve normal W3C `traceparent`, `tracestate`, and `baggage` as well. Runtime identity describes lifecycle ownership; trace identity describes individual distributed operations.

## Services

Do not replace ordinary service APM with runtime sessions. Keep stable `service.name` identity for aggregate service views. Create a `service` runtime only when the lifecycle of a particular process, deploy, replica, or bounded service instance is useful to operators.

For example:

```text
checkout-api service
├── deployment/runtime A
├── deployment/runtime B
└── normal request traces across both
```

## Deep links

Every runtime response includes a canonical console URL:

```text
https://console.telemio.sh/runtimes/<runtime-id>
```

Products integrating Telemio should expose this as a `View in Telemio` action when practical.

Set `externalUrl` when the source product has its own runtime/session page. Telemio then provides the return link from the runtime detail view.

## JavaScript and TypeScript

With `@telemio/sdk`:

```ts
const runtime = await telemio.runtime.start({
  kind: "agent",
  provider: "agent-runtime",
  externalId: session.id,
  externalUrl: session.url
})

console.log(runtime.consoleUrl)

const sessionTelemio = createTelemio(runtime.clientOptions)
```

A child runtime can be created with `runtime.startChild(...)`.

## CLI

```bash
telemio runtime start --kind worker --provider my-worker --external-id "$JOB_ID"
telemio runtime list
telemio runtime link rt_...
telemio runtime end rt_...
```

Use `--json` when another application needs to consume runtime IDs, tokens, or console URLs programmatically.

## Security

Runtime tokens are ingest-only, time bounded, workspace bound, and runtime bound. Ending or revoking the session invalidates the token. Runtime tokens must not grant workspace read access, billing access, API-key management, or administration.

Telemetry export must fail open: an unavailable Telemio endpoint should not make the product fail unless the product explicitly requires telemetry as a hard dependency.