Deploy and monitor

From a flow that works in the Studio to an agent running on its own, reporting what it did — and what to do when it stops.

What a deployment actually is#

There is no platform your agent is uploaded to. A deployment is a folder of ordinary Node code that runs on its own, with the engine vendored inside it and pinned. It will keep running if the Studio is shut down, and it will keep running if the Control Panel is shut down — a board that is down costs a row on a screen, not an answered question.

refund-desk/
  flow.json                 the flow it was generated from
  run.js                    node run.js '{...}' — or --serve to serve it
  src/agent.js              createAgent(options) — the compiled graph
  src/registry.js           createHandlers(), the settings, the bound exports
  src/nodes/<handler>.js     one file per handler    — generated
  src/routers/<name>.js      one file per router     — generated
  src/tools/<name>.js        one file per tool       — generated
  src/services/<name>.js     each service's default  — generated
  src/llm.js                the model behind llm nodes
  src/chat.html             the chat page, self-contained
  test/agent.test.js        smoke tests
  .env.example              every setting it needs, empty
  Dockerfile · .dockerignore
  deploy/nginx.conf.example a proxy, for when more than one person uses it
  vendor/lgflow-<version>.tgz  the engine itself, pinned
  .lgflow/manifest.json     what was generated, and from what
  .lgflow/project.json      what this project is called, and who has worked in it
  .lgflow/journal.jsonl     the durable record of what it has done

1 · Deploy it from the Studio#

1. in the Studio Open the flow and resolve everything in the PROBLEMS bar. A flow with problems can be deployed, but you are choosing to.
2. in the Studio Press Deploy all… and choose the folder to write into.
3. in the Studio Tick what you want done for you: fill a new .env from Settings, npm install afterwards, and put it on the board.
4. in the Studio Press Deploy and watch the log. Each generated file is named as it is written.

Or from the command line#

The Studio's button is a convenience over the same three commands, which is what a build pipeline uses:

npm run check    -- examples/approval-desk/flow.json
npm run generate -- examples/approval-desk/flow.json --out ../refund-desk
cd ../refund-desk && npm install && npm test

The code generator's own model is gpt-5 by default; LGFLOW_CODEGEN_MODEL or --model changes it. That is the model that writes the handlers, which is a different question from the model the agent runs on.

2 · Configure it#

Everything environmental is in the project's .env, and .env.example lists every name the flow needs, empty. Fill in the values on the machine that will run it.

1. on the machine Copy .env.example to .env and fill it in. Model keys, service credentials, MCP server tokens, the board's address and token.
2. on the machine Set the bind if this agent should be reachable from another machine. BIND is the chat's and TRIGGER_BIND is the webhooks', both loopback by default and neither implied by the other.
3. on the machine Run npm test. The generated smoke tests exercise the graph without calling a model.

3 · Start it#

4 · Register it with the Control Panel#

An agent registers itself, outward, over a socket it opens. The board never reaches into an agent — that is the one direction this architecture does not go, which is also why the board cannot test your database for you.

1. on the machine Set the board's address and its token in the agent's .env. The variable names are in .env.example; the values are this deployment's.
2. on the machine Start the agent. On connecting it announces what it is: its flow id, its name, its versions, the capabilities it has, and what it declares it needs.
3. in the Control Panel Find it in the Control Panel. It should be RUNNING within seconds.
4. in the Control Panel If the flow declares MCP servers, open the agent's MCP tab and switch on the tools it may call. An agent on a board that has never been subscribed calls nothing — see the MCP tutorial.

5 · Liveness and health are two different questions#

This distinction is the one to carry away from this page.

A socket that answers a ping proves the process is up, the connection is up and the event loop can answer. It proves nothing about the work: a revoked model key and a database refusing connections both look perfectly green. So an agent checks its own dependencies and reports what it found.

{ "type": "health", "at": "…", "status": "degraded",
  "checks": [ { "name": "openai",     "status": "ok",    "durationMs": 84 },
              { "name": "postgresql", "status": "error", "durationMs": 1002,
                "error": "connect ECONNREFUSED 127.0.0.1:5432" } ] }

6 · Reading what it did#

A run is a run, not a conversation#

Every journal entry says which execution it belongs to, and these five fields are what make a run reassemblable:

runId        the logical run this line is part of
parentRunId  the run that delegated to it, when it is a child
startedBy    what started the whole thing: manual, schedule, event, webhook
triggerId    which trigger, when one did
agent        which delegated agent's work this is

One id per logical run, never a second for the same execution. A chat turn mints one; a triggered run reuses the id the trigger runtime already stamped; a delegated agent gets its own with the parent named. Before this, entries carried only the thread — the conversation — so two runs a second apart were indistinguishable and grouping by it merged unrelated work.

The journal is the durable record; the socket is not#

<project>/.lgflow/journal.jsonl, one JSON object per line, appended. The kinds are llm, tool, turn, trigger, question, approval, form and state. A triggered run writes two lines, enter and exit. state is the one kind that is not about a run at all: it is something the agent became.

This file is on the agent's machine and stays there. What reaches a board is a report about it.

{ "kind": "turn", "outcome": "done", "answered": false,
  "withheld": ["input", "outputs", "steps"] }

A run that answered nothing says so#

A graph that reaches the end with every output channel empty is a successful run by every other measure. The journal records outcome: "done", the board's ok is true, and an agent's drawer read success rate 100.0% · 2 of 2 finished over a run that told the person in front of it nothing.

So there is a separate boolean, answered, and it is a boolean because it had to cross the line that strips payloads: it says whether anything was written and names nothing that was.

What kind of failure it was#

llm · tool · timeout · agent · delegation · validation · trigger · runtime · unknown

Decided from the error's class and its code and which call it came out of — never from its message. The messages are written for a person and are improved whenever somebody has a better sentence; a category that moved when a sentence was reworded would be one nobody could count. The category is written on the failed journal entry and on the run's exit event.

Tokens and cost#

Every model call an agent makes is reported with what it cost, and the board keeps a ledger:

{ "id": "…", "at": "…", "label": "judge for unicell", "model": "gpt-5",
  "tokens": { "input": 120, "output": 3, "total": 123 } }

The id matters in practice: the ledger deduplicates on it, and without one it falls back to the time, the label and the total — so two calls in the same second that happened to cost the same would be filed as one entry.

Thresholds can be set per agent on durationMs, tokens, llmCalls, toolCalls and tokensPerMinute. Released

Tool calls, including MCP#

1. in the Control Panel Open a run. Every model prompt and reply, every tool call with its arguments and its result, every route and every fan-out appears as its own step, in the order it happened.
2. in the Control Panel Filter by category. MCP tool calls is a category of its own, separate from ordinary tool calls.
3. in the Control Panel For what a server actually offered, open that MCP server's Tools tab — filled in by the agents that connected to it, because the board holds no credential and cannot ask.

7 · When an agent waits for a person#

A node that needs a person stops the run and asks. Where the asking happens depends on how the agent is being run.

1. in the agent's chat In the chat, the reply carries Approve and Decline, with the agent's steps folded underneath. A node missing a required argument shows a form instead, filled in with what is already known.
2. on the machine With node run.js at a terminal, approvals are asked at the terminal.
3. on the machine Served, it is POST /resume { thread, answer } — which is how the Studio's Play button and any other host do it.
4. in the Control Panel The approval, and who gave it, is on the run.

8 · Pausing, stopping and restarting#

Restart and recovery#

1. on the machine Restart the process. It re-registers, re-reads its .env, and picks up its journal where it left off.
2. on the machine Waiting conversations survive the restart if the agent is on Node 24 or later and, in a container, if .lgflow is on a volume. Otherwise they are gone and the people waiting will have to start again.
3. in the Control Panel Check the state and the health separately. A restart that fixed the process will not have fixed a revoked key.

9 · Redeploying#

1. in the Studio Change the flow and deploy to the same folder. Only what changed is regenerated, and hand-edited files are left alone.
2. on the machine Run npm install if the engine version moved — vendor/lgflow-<version>.tgz is a new file and the pin points at it.
3. on the machine Restart the process. The old one stands down as the new one takes the flow id.
4. in the Control Panel Confirm the version the board now shows is the one you deployed.

Troubleshooting#

What to do next#

• What a run shows — the tree, the journal, and the four questions kept apart.
• Triggers — a schedule, an event or a webhook, for when nobody is talking to it.
• Monitoring — what the board knows and how it learns it, in full.
• Deployment — what the Studio writes and what it vendors, in full.
• The developer reference — the DSL, the API and the protocol.