Getting Started with the Vention Developer Toolkit

This guide will walk you through creating and running your first machine app using the Starter Template, included in the toolkit.

By the end, you’ll have a fully functional demo app running both locally and in the MachineLogic environment, showcasing real-time control, persistent storage, and a responsive HMI.

Prerequisites

Accounts and Access

Before you begin, ensure you have the following installed and ready:

• A Vention account with access to MachineBuilder and MachineLogic

• A MachineMotion controller in your design (for simulation or real hardware)

Create Your First Machine Design

Start from MachineBuilder on vention.io.

1. Log in to your account.

2. Open an existing design or create a new one that includes a MachineMotion controller.

3. Go to the MachineLogic tab.

4. Click New App → Application Template.

5. Name your application (for example, Quiz Demo).

A new Machine App will appear in your project. It includes a basic demo application and dependencies to get you started.

Link Your Local Development Environment (optional)

You can now link this application to your local machine using the Vention CLI.

Start by creating a new folder on your computer. ( for example, Quiz Demo)

cd MyApp
vention login

This will prompt you to sign in on your browser.

vention pull

Follow the onscreen prompts to choose your design and your Quiz Demo application.

You should now see a local folder containing your new application. The folder structure should look like this:

quiz-demo/
├── customui/                          # React frontend source code
│   └── src/
│       ├── app/                       # Main application components
│       │   ├── pages/                 # Page components
│       │   ├── api.ts                 # Type-safe API client
│       │   ├── app-context.tsx        # React context for state management
│       │   └── app.tsx                # Main app component and router
│       └── main.tsx                   # Application entry point
├── app.py                             # State machine implementation
├── models.py                          # Data models
├── project.json                       # Entry point for your application
├── requirements.txt                   # Python dependencies
├── server.py                          # FastAPI server
└── [build config files]

This structure is intended to mirror a real MachineApp and demonstrates two of the core backend modules of the Vention Developer Toolkit:

• vention-state-machine → state-driven control logic

• vention-storage → data persistence and audit trails

On the frontend, you’ll find components built using @vention/machine-ui and @vention/machine-app-components for a consistent, production-ready HMI experience.

Configuring your application entry point

You can customize how your backend is run by modifying your project.json
Refer to our Python Programming Guide for more information

Set Up Your Local Environment

Before running the demo, you’ll need to install its dependencies.
Creating a Python virtual environment is recommended to avoid version conflicts.

(Optional) Create a Virtual Environment

python3 -m venv .venv
source .venv/bin/activate  

python3 -m venv .venv
.venv\Scripts\activate 

Install Backend Dependencies

pip install -r requirements.txt

Install Frontend Dependencies

cd customui
npm install

Run the Application Locally

Start the Backend

python -m uvicorn server:app --reload

The backend should start on http://localhost:8000.

You can verify it’s running by visiting http://localhost:8000/docs — you’ll see automatically generated API documentation.

Start the Frontend

cd customui
vite

This launches the React development server at http://localhost:4205

Once both processes are running, open your browser to the frontend URL.
You should see the Reach Study Quiz interface appear, communicating live with the backend over WebSocket.

Run the Application in Machine Builder

1. In MachineLogic, open your design and navigate to your app.

2. Click Simulate to start the backend server.

3. Open the HMI — you’ll see the same reach study demo running in the MachineLogic interface.