> ## 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.

# Quickstart

> Install MeshAgent, connect the CLI, run your first agent, and deploy it.

MeshAgent is a platform for building, deploying, and operating room-based agent systems.

If you want to start with built-in agents, you can start in [Powerboards](../interfaces/powerboards) instead. Powerboards is included with your MeshAgent account. Sign in, create a project and room, install one of the built-in agents, and start using it. This guide walks you through installing the MeshAgent CLI and deploying your first agent.

## Step 1: Install the MeshAgent CLI

Choose the installation path that matches how you plan to work.

### Option 1: Install globally

<CodeGroup>
  ```bash macOS theme={null}
  brew tap meshagent/homebrew-meshagent
  brew trust --formula meshagent/homebrew-meshagent/meshagent
  brew install meshagent

  # To install a specific version:
  # brew install meshagent@[version]

  meshagent --help
  ```

  ```bash Windows theme={null}
  choco install meshagent

  # To install a specific version:
  # choco install meshagent --version=[version]

  meshagent --help
  ```

  ```bash Linux theme={null}
  pipx install "meshagent[cli]" --include-deps
  pipx ensurepath

  # To install a specific version:
  # pipx install "meshagent[cli]==[version]" --include-deps

  meshagent --help
  ```
</CodeGroup>

**To update:**

<CodeGroup>
  ```bash macOS theme={null}
  brew update
  brew upgrade meshagent
  ```

  ```bash Windows theme={null}
  choco upgrade meshagent
  ```

  ```bash Linux theme={null}
  pipx upgrade meshagent
  ```
</CodeGroup>

### Option 2: Install in a Python environment

If you are developing with the Python SDK, you can install the CLI in your project environment instead. If you need help setting up Python and `uv`, start with the [Machine Setup Guide](../reference/machine_setup).

<CodeGroup>
  ```bash pip theme={null}
  pip install "meshagent[cli]" # or "meshagent[all]"
  ```

  ```bash uv theme={null}
  uv add "meshagent[cli]" # or "meshagent[all]"
  ```
</CodeGroup>

If you install MeshAgent in a Python virtual environment, you can prefix the commands below with `uv run` instead of activating the environment first. For the full command reference, see [MeshAgent CLI Commands](../reference/meshagent_cli_help).

## Step 2: Connect the CLI to MeshAgent and activate a project

Authenticate in the browser and run the setup flow:

```bash bash theme={null}
meshagent setup
```

`meshagent setup` signs you in, or if you are already signed in lets you continue with the current account or switch accounts, then lets you choose or create a project and activates the project for the CLI. If Codex or Claude are installed, setup can also configure them to use MeshAgent for the active project, reuse or update existing MeshAgent integrations, or remove them when you want to switch back.

At the end of setup, the TUI asks whether you want to create a sample MeshAgent application. Choose that option when you want the guided sample app wizard. It opens the same scaffolding flow as `meshagent create`.

By default MeshAgent provides OpenAI and Anthropic access for the project through MeshAgent-managed routing. You do not need to add your own OpenAI or Anthropic keys first unless you want the project to use your own provider accounts.

If setup or later CLI commands behave unexpectedly, run:

```bash bash theme={null}
meshagent doctor
meshagent doctor --fix
```

`meshagent doctor` checks common local configuration issues. `meshagent doctor --fix` applies the fixes the doctor can safely make for you.

## Step 3: Choose a starting path

You can start from a generated app or run a room-connected process directly.

### Option A: Scaffold a sample app

Use `meshagent create` when you want a deployable sample application that already includes MeshAgent wiring for one of the supported SDKs and app patterns:

```bash bash theme={null}
meshagent create my-meshagent-app
```

The interactive wizard lets you choose the SDK language and app focus. For non-interactive use, pass both values:

```bash bash theme={null}
meshagent create my-python-agent \
  --language python \
  --focus backend-agent
```

Use this path when you want to start from a sample app and then customize the generated project.

### Option B: Run an agent with `meshagent process`

Use `meshagent process` when you want to start a room-connected agent directly from the CLI. Continue below to create a room, connect an agent identity, and optionally deploy it.

**Create a room and mailbox**

If you chose the `meshagent process` path, create the room you will use for this guide now. If you already created a room in the MeshAgent Studio or Powerboards UI, you can reuse it here:

```bash bash theme={null}
meshagent rooms create gettingstarted --if-not-exists
```

This example uses chat, mail, queue, and toolkit channels. Before starting the agent, create the mailbox for the mail channel:

```bash bash theme={null}
# You will need to create a unique email address
meshagent mailbox create \
  --address my-first-agent@mail.meshagent.com \
  --room gettingstarted \
  --queue my-first-agent@mail.meshagent.com
```

**Start your first agent**

`meshagent process` is the main CLI path for running a room-connected agent. This example starts one agent identity with all four primary channels:

* `chat`
* `mail:EMAIL`
* `queue:NAME`
* `toolkit:NAME`

```bash bash theme={null}
meshagent process join \
  --room gettingstarted \
  --agent-name my-first-agent \
  --channel chat \
  --channel mail:my-first-agent@mail.meshagent.com \
  --channel queue:my-first-agent \
  --channel toolkit:my-first-agent \
  --threading-mode default-new \
  --thread-dir ".threads/my-first-agent" \
  --model gpt-5.4 \
  --web-search \
  --storage \
  --rule "You are a helpful first agent. Answer clearly, use web search when needed, and save important artifacts to storage."
```

This keeps the agent running from your terminal. Press `Ctrl+C` when you want to stop it.

**Talk to the agent in MeshAgent Studio**

1. Open [MeshAgent Studio](https://studio.meshagent.com/).
2. Join the `gettingstarted` room.
3. In the participants tab, select `my-first-agent`.
4. Send it a message and ask it to do something that uses the tools you enabled.

At this point you have a live room-connected agent running through the CLI.

You can also open the same room in [Powerboards](https://powerboards.com) if you want to use an end-user-facing UI instead of Studio. Studio and Powerboards both connect to the same underlying room.

**Try the other channels**

You can now reach the same agent through queue, mail, and toolkit entry points.

Send work through the queue:

```bash bash theme={null}
meshagent room queue send \
  --room gettingstarted \
  --queue my-first-agent \
  --json '{"prompt":"Summarize the current room activity and save a note."}'
```

Invoke the toolkit channel:

```bash bash theme={null}
meshagent room agents invoke-tool \
  --room gettingstarted \
  --toolkit my-first-agent \
  --tool run_my_first_agent_task \
  --arguments '{"prompt":"Draft a short welcome message for a new customer."}'
```

You can also email the agent at `my-first-agent@mail.meshagent.com`.

**Deploy the agent as a managed service**

Running the agent locally is the fastest way to test it. When you want it to stay available without keeping your terminal open, deploy it as a service.

The fastest path is to deploy it directly from `meshagent process`:

```bash bash theme={null}
meshagent process deploy \
  --room gettingstarted \
  --service-name my-first-agent \
  --agent-name my-first-agent \
  --channel chat \
  --channel mail:my-first-agent@mail.meshagent.com \
  --channel queue:my-first-agent \
  --channel toolkit:my-first-agent \
  --model gpt-5.4 \
  --web-search \
  --storage
```

If you want to inspect or customize the service manifest first, generate it and deploy it yourself:

```bash bash theme={null}
meshagent process spec \
  --service-name my-first-agent \
  --agent-name my-first-agent \
  --channel chat \
  --channel mail:my-first-agent@mail.meshagent.com \
  --channel queue:my-first-agent \
  --channel toolkit:my-first-agent \
  --model gpt-5.4 \
  --web-search \
  --storage > meshagent.yaml

# Deploy as a room service
meshagent service create --file meshagent.yaml --room gettingstarted

# Deploy as a project service
meshagent service create --file meshagent.yaml --global
```

**Inspect and manage what you deployed**

Use these commands to inspect the project and the services you now have running:

```bash bash theme={null}
# List projects
meshagent project list

# Activate a different project
meshagent project activate -i

# List project services
meshagent service list

# List services in a room
meshagent service list --room gettingstarted

# View service details
meshagent service get <service-id>
```

## Next steps

* [Process Agents Overview](../agents/process/overview): learn how `meshagent process` works and how to shape rules, tools, channels, and threads
* [Powerboards](../interfaces/powerboards): learn how end users can work with deployed and built-in agents
* [Rooms](../room_api/overview): learn the room runtime and built-in room APIs
* [Service YAML](../services/deployment/deploy_services): write service manifests and configure permissions
* [MeshAgent CLI Commands](../reference/meshagent_cli_help): browse the full CLI reference