> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/what-happens-during-a-run.md). # What happens during a run Triggering a flow creates a **flow run**. The executor walks the graph, and for every agent node it creates a **node run**, which the Kubernetes orchestrator turns into a Job in the runs namespace, scheduled under a dedicated service account. ## What is in the pod Beside the agent container runs an **outbox sidecar**. The agent writes events; the sidecar ships them to the controller. That split is why a network blip during a long agent turn does not lose the transcript, and why the agent image does not need to know anything about the controller's API. The pod authenticates with a **short-lived JWT minted for that run**, signed with the controller's pod-token key, and talks over mTLS using material mounted from a Kubernetes secret (`visdom-pod-mtls` by default). The address it posts to is the controller's callback URL. None of this is agent-visible: an agent author writes a shell command and files, nothing more. ## The shared workspace Every flow run gets a directory on a shared persistent volume, mounted into each node's pod. This is how one agent hands work to the next: a design document, a cloned repository, a diff, a test report. It is also where Context Fabric writes the generated `AGENTS.md` that agents read as upfront context. The controller exposes that directory read-only (a tree, individual files, and a `.tar.gz` of the whole thing), which is what the **Memory** view in the UI browses. {% hint style="info" %} There used to be a Memory MCP for cross-agent state. It was removed: **cross-agent state lives on the workspace volume**. If an older document mentions agents sharing memory over MCP, that is out of date: they share a filesystem. {% endhint %} ## Watching a run Two realtime paths exist. A **per-run SSE stream** carries that run's events, and a **WebSocket multiplexer** carries invalidations across the whole UI so lists and counters update without polling. Events are also persisted, so opening a finished run replays it rather than showing an empty log. A run accumulates more than logs: cost ledger entries per node, classifier findings over model output, approvals raised and answered, comments, and any governance alerts it triggered. That is the record the audit story rests on. {% hint style="success" %} **Running the controller on your laptop against a cluster hides the workspace.** The browse endpoints walk the controller's own filesystem. In-cluster that is the same volume the pods use; on a host it is not, so the Memory tab shows nothing and the "browse files" link never appears. The repository ships a mirror script that copies the volume out of the node container; point the workspace directory at it and restart. {% endhint %} ## When a run fails at the very first step Almost always one of three things, in this order of likelihood: an image the cluster cannot pull (a registry alias, or a stopped and restarted local cluster), an edge naming a port that does not exist, or a missing secret. A run that failed on an image pull stays failed even after the registry is fixed, because the Job has already hit its backoff. Trigger a new run rather than waiting for the old one to recover. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/what-happens-during-a-run.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.