Quickstart

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

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

choco install meshagent

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

meshagent --help

pipx install "meshagent[cli]" --include-deps
pipx ensurepath

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

meshagent --help

To update:

brew update
brew upgrade meshagent

choco upgrade meshagent

pipx upgrade meshagent

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.

pip install "meshagent[cli]" # or "meshagent[all]"

uv add "meshagent[cli]" # or "meshagent[all]"

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.

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

Authenticate in the browser and run the setup flow:

bash

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.

Keep logins for multiple environments

Both the Rust and Python CLIs save profiles by API URL and user ID. You can stay logged in to .com and .life even when both accounts have the same ID or email:

meshagent auth login --api-url https://api.meshagent.com
meshagent auth login --api-url https://api.meshagent.life
meshagent auth switch
meshagent auth switch you@example.com --api-url https://api.meshagent.com

Without a profile argument, auth switch lists the saved profiles or opens an interactive picker in a terminal. Each entry shows its environment. Use --api-url to disambiguate a shared ID or email. Switching restores that environment’s session, active project, project API keys, and LLM proxy token. Logging out clears only the selected profile’s session. MESHAGENT_API_URL overrides the saved environment. When set, commands use the saved profile for that URL and do not reuse another environment’s credentials. Unset it to follow the environment selected by auth switch. Existing ~/.meshagent/settings.json files upgrade automatically when the CLI loads settings at startup. The upgrade preserves saved sessions and project settings and uses each profile’s saved API URL. Older profiles without an API URL belong to the default .com environment. Both CLIs read and write the same upgraded format. If setup or later CLI commands behave unexpectedly, run:

bash

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

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

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

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

# 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

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

Open MeshAgent Studio.
Join the gettingstarted room.
In the participants tab, select my-first-agent.
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 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

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

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

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

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

# 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: learn how meshagent process works and how to shape rules, tools, channels, and threads
Powerboards: learn how end users can work with deployed and built-in agents
Rooms: learn the room runtime and built-in room APIs
Service YAML: write service manifests and configure permissions
MeshAgent CLI Commands: browse the full CLI reference

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

Step 1: Install the MeshAgent CLI

Option 1: Install globally

Option 2: Install in a Python environment

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

Keep logins for multiple environments

Step 3: Choose a starting path

Option A: Scaffold a sample app

Option B: Run an agent with `meshagent process`

Next steps

​Step 1: Install the MeshAgent CLI

​Option 1: Install globally

​Option 2: Install in a Python environment

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

​Keep logins for multiple environments

​Step 3: Choose a starting path

​Option A: Scaffold a sample app

​Option B: Run an agent with meshagent process

​Next steps

Step 1: Install the MeshAgent CLI

Option 1: Install globally

Option 2: Install in a Python environment

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

Keep logins for multiple environments

Step 3: Choose a starting path

Option A: Scaffold a sample app

Option B: Run an agent with `meshagent process`

Next steps