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

# Machine Setup Guide

## Python Development Environment Setup

In this guide you will set up your machine to use the MeshAgent Python SDK. Note that **MeshAgent requires Python 3.13**.

We recommend using **uv**, a modern Python tool that:

* Installs the correct Python version automatically
* Creates and manages virtual environments
* Installs dependencies consistently across platforms

## Step 1: Install uv

<CodeGroup>
  ```bash curl theme={null}
  curl -LsSf https://astral.sh/uv/install.sh | sh

  # verify installation 
  uv --version
  ```
</CodeGroup>

## Step 2: Create a project directory

Create a folder where you’ll run the MeshAgent examples:

```bash bash  theme={null}
mkdir meshagent-getting-started && cd meshagent-getting-started
```

If you are using GitHub, clone your repository instead and `cd` into it.

## Step 3: Initialize the project, create a virtual environment, and install MeshAgent

```bash bash  theme={null}
# Pin Python 3.13 for the project and create standard project files
uv init --python 3.13

# Create a virtual environment and download Python 3.13 if not already installed on your machine
uv venv --python 3.13

# Install MeshAgent
uv add "meshagent[all]"
```

> ### How uv commands fit together
>
> * `uv init` initializes the project and records the required Python version
> * `uv venv` ensures that Python version is available and creates the virtual environment
> * `uv add` installs dependencies into the virtual environment

## Step 4: Running commands and activating your virtual environment

With `uv`, you can either activate the virtual environment and run commands normally, or run commands through `uv` using `uv run`, which automatically uses the project’s virtual environment without activation.

### Option A: Activate the virtual environment (recommended for frequent CLI use)

<CodeGroup>
  ```bash macOS/Linux theme={null}
  source .venv/bin/activate
  ```

  ```bash Windows theme={null}
  .venv\Scripts\activate
  ```
</CodeGroup>

You’ll know the environment is active when you see `(.venv)` at the start of your terminal prompt. With the environment activated you can run commands directly:

```bash bash  theme={null}
meshagent setup
python your_script.py
```

### Option B: Use `uv run` (no env activation required)

If you prefer not to activate the virtual environment, prefix commands with `uv run`:

```bash bash  theme={null}
uv run meshagent setup
uv run python your_script.py
```

## Keeping your environment up to date

To upgrade MeshAgent and other dependencies to their latest compatible versions, run:

```bash bash  theme={null}
uv lock --upgrade
uv sync
```

> ### `uv lock` vs `uv sync`
>
> * `uv lock` updates the dependency versions recorded for the project
> * `uv sync` installs the versions recorded in the lockfile into your virtual environment

## Next Steps

You're ready to continue with the [Quickstart](../introduction/cli_quickstart) guide.

### Troubleshooting

Command not found (`meshagent`, `python`):

* Make sure the virtual environment is activated and you are in the correct project directory
* Or use `uv run meshagent` or \`uv run pyhton…\`\`\`

Permission issues:

* On macOS/Linux, you might need to restart your terminal after installing uv, or run `source ~/.bashrc` or `source ~/.zshrc`.