---
title: "Getting Started"
slug: "getting-started"
updated: 2026-05-20T14:22:07Z
published: 2026-05-20T14:22:07Z
canonical: "docs.vention.com/getting-started"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

# 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

> [!NOTE]
> 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)

| Tool | Purpose | Installation |
| --- | --- | --- |
| **Python 3.10** | Backend runtime | [python.org/downloads](https://www.python.org/downloads/) |
| **Node.js + npm** | Frontend runtime | [nodejs.org](http://nodejs.org) |
| **Vention CLI** | Sync projects between local and cloud | `npm install -g @vention/vention-cli` |
| **Graphviz** *(optional)* | Enables state/DB diagram generation | `brew install graphviz` or `apt install graphviz` |

## Create Your First Machine Design

Start from **MachineBuilder** on [vention.io](http://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`)

```bash
cd MyApp
vention login
```

This will prompt you to sign in on your browser.

```bash
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:

```plaintext
quiz-demo/
├── ui/                                # Prebuilt react frontend
├── 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.

> [!NOTE]
> Configuring your application entry point
> 
> You can customize how your backend is run by modifying your `project.json` Refer to our [Python Programming Guide](/technicaldocumentation/docs/machinelogic-python-programming-guide#310-projectjson) 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

macOS / LinuxWindows

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

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

### Install Backend Dependencies

```bash
pip install -r requirements.txt
```

### Install Frontend Dependencies

```bash
cd customui
npm install
```

## Run the Application Locally

### Start the Backend

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

```bash
cd customui
npm run dev
```

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.