MBEstudio User Guide

1.1What MBEstudio is

MBEstudio is a SysML v2 engineering studio. The model is source text. The 3D view, diagrams, budgets, bill of materials and requirement verdicts are all derived from that text, so editing the text updates every view.

You can describe a system in plain words and let the agent write the model, open one of the bundled examples, or write SysML v2 yourself.

1.2Open it in a browser

The studio runs at studio.vectorstreamsystems.com with nothing to install. A recent Chrome, Edge, Firefox or Safari with WebGL works. Your model is saved in the browser as you type, and the last model you had open reopens on your next visit.

1.3Install on Linux

Debian 12 or later, Ubuntu 22.04 or later, or Pop!_OS, on x64. First add the package repository:

curl -fsSL https://apt.vectorstreamsystems.com/setup.sh | sudo sh

Then install the package:

sudo apt install mbestudio

The package installs three programs:

• mbestudio-desktop: the studio in its own window, with a menu entry and icon. Links to other sites open in your normal browser.
• mbes: the SysML v2 compiler on the command line (see The mbes command line).
• mbestudio: a terminal launcher that connects Claude Code, Codex or Kimi to the studio (see Connecting AI agents). It needs Node.js 18 or later.

To update, run sudo apt update && sudo apt upgrade. To remove it, run sudo apt remove mbestudio.

1.4Windows and macOS

The Windows installer is on the download page. It installs for the current user, needs no admin rights, and updates itself. The macOS installer is not published yet; on a Mac, use the studio in your browser, which is the same app.

1.5Sign in

You can try the studio without an account. You get one free agent generation and a number of free part searches while signed out.

To sign in, enter your email and choose Email me a sign-in link. There is no password. The email has a link and a 6-digit code; open the link, or type the code into the studio. A link works once and expires after 15 minutes, so request a new one with Resend link if it has lapsed. A sign-in lasts 30 days.

New accounts start with 300 free credits. When you need an account, for a second generation, an export or after five minutes of use while signed out, the studio asks you to create one. Your model stays saved in the browser and is waiting when you sign in.

2.1The top bar

From left to right:

• Ask agent opens the agent in the side panel.
• The workspace button shows the model's name and opens the Workspaces dialog (see Workspaces).
• File, Model, Undo, Redo and Export.
• The theme switch: Light, Dark, or Follow the system.
• Connect shows how to connect Claude, Cursor or another MCP client.

You can also drop a file anywhere on the window to open it.

2.2The three panes

• Left: the SysML text editor. This is the model. Wrap lines toggles wrapping. Press [ to hide or show it.
• Centre: the model views. The 3D view, Graph, Diagrams and the analysis views, with a collapsible Model tree (press \). Tabs that do not fit go under More. Chapter 5 describes each view.
• Right: the side panel. Tabs for Agent, Inspector, Findings, Variants, Data and Trade. Press ] to hide or show it.

An empty model shows New model and Open an example.

3.1Workspaces

A workspace holds one model. The Workspaces dialog lets you create a workspace (blank, or starting from an example), open, rename or duplicate one, and open a .sysml, .kerml or .mbes.json file as a new workspace. Workspaces are kept in your browser; sign in and use File, Versions to keep saved versions with your account.

3.2Bundled examples

Model, Examples opens any of these. You can also link straight to one with ?example=. An example link keeps its own draft, so opening it never overwrites your own model.

3.3Open and save files

The Model menu has New model, Open file (.sysml, .kerml or .txt), Examples and Clear model. The File menu adds Open SysML or .mbes.json, Save SysML, Versions and Federation.

3.4Import from other tools

The File menu imports from each source type:

4.1Describe the system

Choose Ask agent. In the box labelled Describe the system to model, write what you want in plain words, with the constraints that matter, for example: a battery powered field sensor that reports hourly over a radio link, under 2 kg. Choose Generate or press Ctrl+Enter (Cmd+Enter on a Mac).

4.2While it runs

The panel shows the plan, how many parts have been validated, and the text being written. The 3D view can show the generation preview as it grows. A cost line shows the credits this generation has used and how many you have left. Cancel stops the run.

4.3Accept the result

Nothing in your editor changes until you choose. When the generated model compiles, pick one of:

• Replace model: the generated model replaces yours.
• Append to model: it is added to your current model.
• Download source: save it as a file instead.
• Discard.

If it does not compile yet, Keep going carries on from where it stopped, and Open draft in editor lets you fix it by hand.

4.4Change an existing model

The Change this model box asks for an edit to the model you have open, for example add a second battery pack in parallel. Choose Propose change, review it, then Apply change, Download draft or Discard.

5.13D

The model in 3D. The toolbar has the tools Select (Q), Move (W), Rotate (E) and Connect (C), a snap setting (none, 1 cm, 10 cm, 0.5 m or 1 m), and actions to add a part, add a port and connect ports.

Fit (F) frames the model; Front, Side, Top and Iso are 1 to 4. Toggle X-ray to show internals (X), sensor fields of view (V), ports (P) and part labels (L). You can tag parts whose size is estimated, colour parts by a property with a legend, and show every hidden part again.

Moving or resizing a part in 3D writes the change back into the SysML text. The text stays the source of truth.

5.2Graph and Diagrams

Graph shows the model as a graph of its elements and relationships. Diagrams lists the model's internal block diagrams, state machines and sequences, and can create a new sequence or use case.

5.3Requirements

Every requirement with its verdict, its value against its limit, the margin, and its trace. A coverage strip counts the verdicts. Filter to the selected part, or add a statement.

5.4Interfaces, Budgets and BOM

• Interfaces: the netlist, the interface control table and the port list.
• Budgets: demand against supply for each bus or the whole system, with a utilisation bar and margin.
• BOM: an indented tree or flat list with quantities and mass, and where each mass came from.

5.5Functions, Ontology, Safety and Review

• Functions: add behaviours and their parameters.
• Ontology: add definitions, rename, change a type, add members.
• Safety: integrity allocation, isolation groups and findings.
• Review: values the model relies on but does not state.

5.6Physics

Joint reactions under each load case against their capacities, parts with no load path to a support, and a rigid-body motion replay.

5.7Report

The system report: summary, requirements, constraints, findings, part tree, interfaces, state machines and variants. Download it as a self-contained HTML file or print it.

6.1Running a simulation

The Simulation view runs by itself once the model compiles and has a state machine. Set Stop to a time in seconds, or leave it empty for automatic. Use Play and Pause, zoom, Fit, and the speed: Overview, Real time, 4x or 0.25x. The t = readout shows the current time.

The run summary counts transitions and requirements satisfied, violated, indeterminate and not applicable, and flags any requirement whose run verdict differs from its static verdict.

6.2Reading a verdict

The static verdict uses the declared values. The run verdict judges every stretch of the run where the requirement's assumptions hold.

7.1Formats

The Export menu offers:

Exporting needs a free account.

8.1About the language

MBEstudio uses native SysML v2 source for parts, typed interfaces, equations, requirements and behavior. The current compiler implements a supported language subset with a geometry profile.

8.2Quantities and units

Import the types and units you use, such as ISQ::* and SI::*. Write a quantity as 40 [W] or 0.1 [s]. The compiler checks dimensional consistency. Metadata fields such as rangeM or yawDeg use literal numbers in the units named by the field.

8.3A model is source text

A package contains definitions and usages. A top-level part usage is the system to elaborate. Model chooses an example or opens a SysML text file; Export saves the source. JSON exports represent derived data, not the native authoring format.

8.4Parts and attributes

Use part def for a reusable type and part name : Type for an instance. Attributes can be stated values, expressions or missing inputs. A missing measurement remains unknown. Use default = for an initial value that a state machine can assign during a run.

8.5Authored geometry and placement

The MBEstudio profile adds placement, material, envelope and field-of-view metadata. Body features include extrusions, revolutions, lofts and Boolean operations. The hatchback uses polygon-section lofts for its body and glazing. Packaging envelopes and authored material geometry serve different checks.

8.6Typed ports

A port def declares the features exchanged at an endpoint. Port usages reference the type; a conjugated type uses ~ to reverse its direction. Inspect ports in 3D, Interfaces and the internal block diagram.

8.7Interfaces and connections

An interface def declares typed ends. An interface usage connects the actual part ports. The hatchback includes electrical power, data, fluid and shaft-torque interfaces. A displayed connection establishes modeled connectivity; it is not automatically a detailed manufactured wire route.

8.8State behavior

Declare a state machine inside a part, name its initial state with entry; then idle;, and use timed triggers or guards. State entry assignments change model attributes. Simulation evaluates the resulting sequence and Diagrams displays its structure.

package CoolingStudy {
    private import ISQ::*; private import SI::*;
    part def Controller {
        attribute output : PowerValue default = 0 [W];
        state modes {
            entry; then idle;
            state idle;
            state active { entry assign output := 40 [W]; }
            transition start first idle accept after 2 [s] then active;
        }
        constraint withinBudget { output <= 50 [W] }
    }
    part controller : Controller;
}

The current simulator runs top-level machines on their owning instances. Nested composite-state execution is not implemented.

8.9Requirements and executable checks

Declare a requirement def with a subject and require constraint. A satisfy relationship identifies the implementing subject. A boolean expression determines satisfaction; a numeric comparison can produce a value, limit and margin. Use assume constraint for applicability conditions over a simulation run.

8.10Interpret results and exports

Requirements can be satisfied, violated or indeterminate. Simulation also shows not-applicable intervals when assumptions are false. Stated dimensions, response delays and sensor fields remain design assumptions until verified. Review the source, requirement results, budgets, BOM and report together.

Current limitations describe the boundary of these checks. The bundled examples are the most direct reference for syntax accepted by the deployed compiler.

9.1The MCP server

MBEstudio is an MCP server, so Claude Code, Claude Desktop, Cursor, Codex and other MCP clients can build and check models for you. The endpoint uses Streamable HTTP with OAuth sign-in:

https://studio.vectorstreamsystems.com/mcp

The Connect button in the studio shows the setup for each client and the list of tools. Tools that only read status are free; tools that generate, simulate, verify or export use credits.

9.2Claude Code

claude mcp add --transport http --scope user mbestudio https://studio.vectorstreamsystems.com/mcp

Then run /mcp in Claude Code and choose Authenticate.

9.3The mbestudio launcher (Linux)

The Linux package adds the server for you. mbestudio claude, mbestudio codex or mbestudio kimi adds the MCP server if it is missing, then starts that agent in the terminal. It never overwrites an existing mbestudio entry that points somewhere else.

10.1Commands

mbes compiles and evaluates SysML v2 files without the studio, which suits scripts and CI.

11.1Credits

Agent work is paid in credits at $0.01 a credit. A run reserves credits while it works and returns what it does not use; the agent panel shows the cost as it goes. Credit packs are one-time purchases, need no subscription and do not expire. Plans include monthly credits. See Pricing for the current plans and packs.

11.2Your account page

Your account page lists your saved models, billing and credits, and agent connections. It shows each job with its tokens and credits, where you can open its model or cancel it, and lets you set a monthly cap on usage beyond your included credits. Sign out and delete your account from here too.

12.1Shortcuts

Shortcuts are ignored while you are typing in a field.

On a Mac, use Cmd for Ctrl.

13.1On a phone

On a narrow screen the studio opens a phone preview: the agent prompt, the 3D view and a tappable parts list. Editing, diagrams, requirements and analysis need a larger screen; Open the full studio switches to the desktop layout for the session.

13.2Troubleshooting

Still stuck? Contact us.