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

# Process Agents

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](https://studio.meshagent.com) 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

| Channel        | Use it for                                                                       |
| -------------- | -------------------------------------------------------------------------------- |
| `chat`         | Interactive conversation in MeshAgent Studio, Powerboards, or other chat clients |
| `mail:EMAIL`   | Turning inbound email into agent work                                            |
| `queue:NAME`   | Running background jobs from a room queue                                        |
| `toolkit:NAME` | Letting 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.

## Choose a backend

The backend is the part of the process agent that handles a turn after a channel delivers it.

| Backend | How to select it                                                   | Use                                                              |
| ------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| LLM     | `--model gpt-5.5`, another standard model name, or `--backend llm` | General-purpose process agents that use MeshAgent's LLM adapters |
| Codex   | `--backend codex` or `--model codex/gpt-5.5`                       | Room-connected agents whose turns should be handled by Codex     |

Most process agents use the LLM backend. Use the [Codex Process Backend](./codex_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:

```bash theme={null}
meshagent process join \
  --room gettingstarted \
  --agent-name support-agent \
  --channel chat \
  --model gpt-5.5 \
  --model codex/gpt-5.5
```

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](../threads_overview).

## Main commands

| Command                    | Use                                             |
| -------------------------- | ----------------------------------------------- |
| `meshagent process join`   | Run the agent locally in a room                 |
| `meshagent process run`    | Run the agent and wait for interactive messages |
| `meshagent process use`    | Send work to a running process agent            |
| `meshagent process spec`   | Generate a service manifest from CLI flags      |
| `meshagent process deploy` | Deploy the agent as a service                   |

## Where to go next

* [Codex Process Backend](./codex_backend): run a room-connected process agent with Codex as the backend
* [Agent Turns](./agent_turns): understand how one request becomes one process-backed turn and how turn lifecycle differs from plain messages
* [Process Agent Architecture](./architecture): understand how channels, supervisors, and per-thread execution fit together
* [Threads Overview](../threads_overview): understand thread paths, thread directories, and persisted continuity
* [Tools and Toolkits](../tools/tools_and_toolkits): understand built-in tools, custom tools, and toolkit patterns
* [Queues and Scheduled Tasks](../queues_and_scheduled_tasks): use queues for background work