MindVM documentation

A MindVM agent is a folder of files. You write it, mindvm validate checks it without a server, mindvm dev pushes it, and the runtime resolves those files on every run — so what runs is what is on disk, and an AI coding tool can edit an agent the way it edits anything else.

These docs are being rebuilt

MindVM was recently rebuilt on a new platform, and most of what was here described the surface it had before. Rather than leave pages that no longer match, they were removed. What remains is current.

The CLI reference is the authoring loop end to end. The REST API is described by the OpenAPI document the server itself prints, which is the only description that cannot drift.

What is here

The CLI

init, validate, dev, run, eval, deploy — the whole authoring loop, and the exit code a CI job gates on. Reference →

The API

Generated from the server, so it cannot describe a route that does not exist. Run mindvm openapi for the document, or read it at /api/docs on any deployment.

The shape of an agent

mindvm/
  mindvm.jsonc              the project this folder belongs to
  agents/
    starter/
      agent.jsonc           what this agent is: model, persona, skills, evals
      persona.md            how it should behave
      skills/now/skill.md   what the model reads about a skill
      skills/now/main.js    what a script gets when it require()s it
      evals/basics.json     what a good answer looks like
      routines/             scripts promoted from successful runs

Everything is a declaration: agent.jsonc names the files it uses, and resolution follows those names. A persona.md the config does not name is a file the agent does not have — nothing is inferred from a filename.

Reasoning by writing code

The agent’s primary move is a think block: JavaScript, run in a sandbox, with its variables carried into the next turn.

function run(args) {
  const hits = search("returns policy", { limit: 5 });
  const best = hits.filter((h) => h.score > 0.7);
  log("found " + hits.length + ", kept " + best.length);
  answer("The policy says: " + best[0].content);
}

What that buys is one turn instead of four. An agent that had to call a search tool, read the result, call a filter tool and read that again would spend a round trip per step and carry every intermediate result through its context window. Here the search, the filter and the answer happen in one script, and only what it chooses to log() reaches the next prompt.

The value a block returns is threaded into the next turn as args, held server-side rather than serialised back into the prompt — so a many-step run does not grow a context window.

Getting started

git clone https://github.com/mind-vm/studio-apps-ng
cd studio-apps-ng/apps/mindvm
make cli

export MINDVM_URL=https://platform.mindvm.ai
export MINDVM_ORG_ID=<uuid>
export MINDVM_API_KEY=mvk_…

bin/mindvm init
bin/mindvm validate
bin/mindvm dev
bin/mindvm run starter "What is 127 times 43?"

The CLI reference explains each verb and what it is for.