Skip to main content
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:
Then start one agent with chat, mail, queue, and toolkit channels:
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:

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

​
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:
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: 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.

​
Choose a backend

The backend is the part of the process agent that handles a turn after a channel delivers it. Most process agents use the LLM backend. Use the Codex Process Backend page when you want the same process-agent channel and deployment model, but Codex handling the turns. Use --model when you want to choose the exact model or models the agent can use. --model can be repeated. A plain model name such as gpt-5.5 selects the LLM backend. A backend-qualified model such as codex/gpt-5.5 selects the Codex backend. Use --backend when you want to make a backend’s default model set available without naming every model yourself. --backend llm currently adds llm/openai/gpt-5.2 and llm/anthropic/claude-3-5-sonnet-latest. --backend codex currently adds codex/gpt-5.5. If you omit both --backend and --model, the command defaults to --model gpt-5.5. You can also make more than one backend available from the same running agent by passing multiple model flags:
With the default dataset-backed thread storage, the same agent can switch between those models on the same thread. In chat, use /models to see the available models, then use /model with a backend-qualified model when needed, such as codex/gpt-5.5. Keep the default dataset storage for this pattern; Codex thread storage only supports Codex backends.

​
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 persisted thread history is organized
  • --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

​
Where to go next