Skip to main content
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 install meshagent

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

meshagent --help
To update: 
brew update
brew 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]"
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. 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
  1. Open MeshAgent Studio.
  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 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