An approval pauses the run, not a workerA paused run releases its lease and holds no worker. It waits until someone decides, then the approval node returns the decision and the run continues from that step.Why every execution is pinned to one versionAn execution records its workflow version once, when it starts, and never follows a live pointer. That is why resume and replay still mean something weeks after a graph has changed.Memory has a subject, a namespace, and an expiryEvery memory fact lives under a key, a subject and a namespace, and it always expires: 90 days by default, one year at most. Here is how writes, reads and sharing work.What happens when a worker dies mid-runA worker holds a 30 second lease and renews it every 10 seconds. If it dies, the lease expires, another worker claims the run, and the run resumes from the last checkpoint.Which Linea client to use, and which key goes whereThe TypeScript SDK has a server client, an environment client for production starts, an end-user client for browsers, and a webhook verifier. Each one takes a different credential.Linea Labs is not Consensys LineaLinea Labs builds Linea, an open-source AI agent runtime at getlinea.app. It is not the Consensys Linea blockchain, and not the Linea Sketch iPad app.What is an AI agent runtime?A framework gives you the agent loop. A runtime runs it in production: durable steps, checkpoints, approvals, crash recovery, and replaying one failed step.Why replay needs the checkpointYou cannot re-run step four without the exact input it saw. That input only exists if the host executed the run and kept the checkpoint.One graph, not two productsThe canvas, the workflow JSON, and the node registry describe one thing. A second editor is fine. A second graph is a second product.The half frameworks do not shipFrameworks solve the loop. You still host it, retry it, store its memory, and keep its checkpoints. That second half is the product.Memory is not a side questFacts have to survive the run. If you stand up the store yourself, you are still doing the ops half. We think the graph should ask for memory and the host should keep it.Sandbox the code nodeA code node is an escape hatch. It still has to run somewhere that cannot take down the host. Linea does not ship one yet, and this is why.Triggers are not the productStarting a graph is a solved problem. The product is what has to stay up after it starts: the worker, the checkpoint, the wait, and the memory.
Toggle menu

Which Linea client to use, and which key goes where

The TypeScript SDK has a server client, an environment client for production starts, an end-user client for browsers, and a webhook verifier. Each one takes a different credential.

Linea Labs
  • SDK
  • Builder

The Linea TypeScript SDK is not one client. It is four entry points, and each one is built for a different place your code runs and a different credential it is allowed to hold. Picking the right one is mostly a question of where the code lives.

This post sorts them out using the SDK's own documentation, and ends with the limits worth knowing before you build on it.

Four entry points

Entry pointRuns whereCredentialWhat it is for
`Linea`Your server, a script, a CI jobA workspace API keyBuild, run and monitor workflows
`LineaEnvironmentClient`Your serverAn environment keyStart production runs
`@linealabs/sdk/user`Browser, edge, nativeA verified end user sessionStart and follow runs for one user
`@linealabs/sdk/webhooks`Your serverWebhook secretVerify webhook deliveries

The first rule follows from the table. A workspace API key is a bearer credential for the whole workspace, so it never leaves trusted server code. The end-user entry point exists so that browsers and devices never need one. It does not accept an API key at all.

Pick the client by where the code runs. Each one takes a different credential.

The server client

Linea takes a workspace API key and groups its methods by resource: workflows, executions, signals, regressions and audit events.

TypeScript

import { Linea } from "@linealabs/sdk"

const linea = new Linea({ apiKey: process.env.LINEA_API_KEY! })

const execution = await linea.workflows.run(workflow.id, {
  input: { ticketId: "T-123" },
})
const { execution: finished, steps } = await linea.executions.wait(execution.id)
console.log(finished.status, steps.length)

run starts the version bound to the dev environment. wait polls every second until the execution succeeds, fails or is cancelled, and gives up with a timeout error after five minutes. You can change both with intervalMs and timeoutMs.

The same client can also create workflows and save drafts and versions, because workflows have a write scope. What it cannot do is publish. Publishing a version and binding it to an environment need a signed-in workspace admin, so those two steps happen in the dashboard. That split is deliberate: an API key can prepare a graph, but a person releases it.

Keys are scoped, and they expire

An API key is created in the dashboard under Settings, then API Keys, by an admin session. A key cannot create other keys, so a leaked key cannot mint more of itself. The raw key is shown once.

Each key carries an explicit list of scopes and a lifetime of 1 to 365 days. Grant only what the integration calls:

  • workflows:read and workflows:write for managing workflows
  • executions:start for starting a run
  • executions:read for reading executions
  • signals:read and signals:write for signals

A key also stops working when the admin who created it leaves the workspace or loses the admin role. Plan for that: a key tied to one person's role is a key that can quietly stop.

Running in production

Production starts use the environment client with an environment key from the environment's Backend keys tab. The workflow binding must also allow backend starts, so a key alone is not enough.

TypeScript

import { LineaEnvironmentClient, environmentKey } from "@linealabs/sdk"

const production = new LineaEnvironmentClient({
  environmentId: "env_123",
  environmentKey: environmentKey(process.env.LINEA_ENVIRONMENT_KEY!),
})

const started = await production.startExecution({
  workflowId: "wf_123",
  externalSubjectId: "user_123",
  input: { ticketId: "T-123" },
})
const result = await production.waitForExecution(started.id)
console.log(result.status, result.output)

Notice externalSubjectId. It names the person the run is for, which is what memory is keyed on later.

Browsers and devices

The end-user client is the one that is safe to ship. It starts an authorization, completes it after the redirect, and keeps only an opaque session bound to a proof key. Browsers keep that state in IndexedDB, edge runtimes keep it in memory, and React Native apps supply their own secure storage.

From there it can create a conversation, start an execution, refresh it, and stream events. Event notifications are hints, not state. After a reconnect the client emits a reconciled event, and you should replace your local snapshot with the authoritative list before handling later events.

Limits to know about

Read these before you build.

  • No automatic retries. A failed request is never retried for you. Retrying a call like workflows.run can start a duplicate execution, so that decision is left to your code.
  • Reads are capped for one workflow. Listing executions for a single workflow returns at most 50 rows, with no pagination. The general execution list does paginate with a cursor.
  • Costs arrive as strings. costMicros is a 64-bit integer, so it comes over JSON as a decimal string. Convert it before doing arithmetic.
  • Two error types. Requests throw an API error when the server answered with a failure, and a network error when the request never arrived. Handle both.

Start from where your code runs. A server script uses Linea, a production backend uses the environment client, and anything that ships to a user uses the end-user entry point. The credential follows from that choice, and so do most of the mistakes you avoid.

The Linea newsletter

What we learn from every run.

New releases and field notes on running agents in production.

One email when something ships. Unsubscribe anytime.