> 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/concepts-and-the-object-model.md).

# Concepts and the object model

Nine objects carry almost everything. Learning them in this order makes the rest of the UI readable.

**Workspace** is the top-level tenant. Secrets, RBAC grants, quotas, egress policies, identities and the audit chain are workspace-scoped. On first sign-in, any verified email listed in `VP_BOOTSTRAP_ADMINS` is granted Admin at workspace scope, idempotently.

**Project** is a unit of work inside a workspace. Agents, flows and runs belong to a project. The project **slug** matters beyond the Orchestrator: it is how the shared workspace drive is paired with Context Fabric, so the same slug has to be used on both sides.

**Container definition** is an image plus the metadata needed to schedule it. Agents reference containers rather than raw image strings, so an image bump is one edit rather than a search across agents.

**MCP definition** is an MCP server an agent may use. Configured per agent, with a method allow-list, so "this agent may call these tools and nothing else" is expressible.

**Agent definition** is the interesting one. It carries a runtime (image, model, command), typed **input and output ports**, required MCPs, an egress allow-list, a system prompt, and an agent doc mounted as `CLAUDE.md`. It has a `mode`:

* `agent`: an LLM drives the work inside the pod
* `deterministic`: a fixed command runs and reports

Both expose the same ports, which is why a flow can mix an LLM reviewer with a plain test runner and treat them identically.

**Flow definition** is a versioned graph: nodes, edges, parameters, trigger kinds. Flows are validated against a schema catalog before they can be saved.

**Flow run** is one execution. It owns the run status, the event stream, the cost ledger entries, the approvals raised, the comments, and the workspace directory the pods share.

**Node run** is one node's execution inside a flow run. This is what becomes a Kubernetes Job, and what carries the per-node outputs that downstream nodes read.

**Memory entry** is workspace-scoped knowledge available to agents, with a secret scanner over it and sensitive entries pushed into the encrypted secret store.

{% hint style="success" %}
**Agents are forked, not shared.** Installing a flow template or forking a catalog agent copies it into your project and records where it came from. Your edits are yours; the upgrade scanner later tells you a newer catalog version exists, and you decide. Nothing upstream reaches into a project and changes a definition underneath a running flow.
{% endhint %}

## What is versioned, and what is not

Agent definitions and flow definitions carry explicit integer versions, and a flow node pins the agent version it wants (`agent_version: 1`). Catalog manifests carry their own `(name, version)` pair, recorded on the forked or installed row so the upgrade scanner can compare. Runs are immutable records of what actually executed.

Secrets, quotas and policies are **not** versioned per run. Approval policies are the exception: they are consulted by version at the moment an approval node dispatches. When reconstructing why a run behaved a certain way, the definition versions and the audit log are reliable; "what was the egress policy that afternoon" is not directly answerable from the run.


---

# 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/concepts-and-the-object-model.md?ask=<question>&goal=<endgoal>
```

`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.