Skip to main content

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.

meshagent process is the main CLI runtime for agents that stay available in a room. Use it when you want one agent identity that people can talk to conversationally and that can also handle background work from queues, mail, or toolkit calls.

​
Run a multi-channel process agent locally

If you want the agent to receive email, create the mailbox first: 
meshagent mailbox create \
  --address support-agent@mail.meshagent.com \
  --room quickstart \
  --queue support-agent@mail.meshagent.com
Then start one agent with chat, mail, queue, and toolkit channels: 
meshagent process join \
  --room quickstart \
  --agent-name support-agent \
  --channel chat \
  --channel mail:support-agent@mail.meshagent.com \
  --channel queue:support-jobs \
  --channel toolkit:support-agent \
  --threading-mode default-new \
  --thread-dir ".threads/support-agent" \
  --web-search \
  --storage \
  --rule "You are a helpful support agent. Answer clearly, use web search when needed, and save important artifacts to storage."
This gives you one room-connected agent that:
  • can be reached through chat, mail, queue, and toolkit channels
  • keeps thread history under .threads/support-agent
  • has built-in web search and storage tools
  • has one inline rule
This is the default meshagent process pattern: one long-running agent can serve several entry points while keeping continuity organized by thread. If you want to see more channels, model options, and built-in tool flags, run: 
meshagent process join --help

​
How to reach the agent

Once the process is running, you can use the same agent in a few different ways.

​
Chat with it conversationally

Open the same room in MeshAgent Studio and start chatting with support-agent.
  • MeshAgent Studio is the main place to test the agent while you are building
  • you can inspect the room, participants, logs, traces, and metrics while the process is running

​
Send background work through the queue

Use the queue channel when you want the same agent to do non-interactive work: 
meshagent room queue send \
  --room quickstart \
  --queue support-jobs \
  --json '{"prompt":"Summarize the current support backlog and save a report."}'
This is the background-task path. It is useful for recurring jobs, automation, imports, and other work that should not start from a live chat message.

​
Invoke it from another agent or app

Use the toolkit channel when another participant should be able to call this agent as a tool: 
meshagent room agents invoke-tool \
  --room quickstart \
  --toolkit support-agent \
  --tool run_support_agent_task \
  --arguments '{"prompt":"Draft a short reply explaining the refund policy."}'

​
Send it email

If you enabled mail:support-agent@mail.meshagent.com, you can also email the agent at that address and let the mail channel turn the message into room work.

​
Deploy the same agent

When the local version looks right, deploy the same agent shape so it stays available without your terminal open: 
meshagent process deploy \
  --service-name support-agent \
  --room quickstart \
  --agent-name support-agent \
  --channel chat \
  --channel mail:support-agent@mail.meshagent.com \
  --channel queue:support-jobs \
  --channel toolkit:support-agent \
  --threading-mode default-new \
  --thread-dir ".threads/support-agent" \
  --web-search \
  --storage \
  --rule "You are a helpful support agent. Answer clearly, use web search when needed, and save important artifacts to storage."
Use meshagent process join while developing and meshagent process deploy when you want the agent to stay available as a room or project service.

​
What meshagent process is

Supported channels:
ChannelUse it for
chatInteractive conversation in MeshAgent Studio, Powerboards, or other chat clients
mail:EMAILTurning inbound email into agent work
queue:NAMERunning background jobs from a room queue
toolkit:NAMELetting other agents or apps call this agent like a toolkit
Each --channel flag adds another entry point to the same running agent. The core idea is simple:
  • the agent is the running participant
  • the channels are how work reaches that agent
  • the thread is the continuity boundary
That means one running agent can serve several entry points without automatically mixing unrelated work together. Work shares continuity when it uses the same thread path.

​
Shape the agent with rules and tools

The process command is also where you shape what the agent can do.
  • use --rule for inline instructions
  • use --room-rules when you want editable room-backed rules
  • use tool flags such as --web-search, --storage, --mcp, --shell, or --advanced-shell to add capabilities
  • choose the model with --model
That means meshagent process is not just how the agent starts. It is also how you define its channels, rules, tools, and continuity behavior.

​
When to use meshagent process

Use meshagent process when you want an agent that should:
  • stay available over time instead of acting like a one-shot run
  • work across chat, mail, queues, or toolkit calls
  • keep one rules and tools setup across those entry points
  • preserve thread continuity across longer workflows
  • be easy to run locally and then deploy with the CLI

​
Threads and continuity

Thread configuration matters most when the agent needs durable history.
  • --thread-dir controls where thread documents are stored
  • --threading-mode controls how chat-oriented clients treat thread creation and selection
Use a dedicated thread directory when you want one agent to support many conversations or jobs without mixing them together. For the deeper persistence model, see Threads Overview.

​
Main commands

CommandUse
meshagent process joinRun the agent locally in a room
meshagent process runRun the agent and wait for interactive messages
meshagent process useSend work to a running process agent
meshagent process specGenerate a service manifest from CLI flags
meshagent process deployDeploy the agent as a service

​
Where to go next