> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rallied.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ImmyBot

> How the agent reads each customer's ImmyBot computers, software and maintenance sessions, and, after a technician approves, deploys software or runs a task on one computer.

Connect your ImmyBot instance and the agent works Windows computer tickets with ImmyBot data, without a technician opening ImmyBot.

When a ticket says a computer is missing an app, a maintenance run failed or a machine is acting up, the agent finds the computer in ImmyBot, reads what ImmyBot says needs attention and what its last session logged, and writes it up in an internal note. It then proposes a fix on that one computer: install or update a library app, run a library maintenance task, or run a PowerShell script it wrote. Nothing changes until a technician approves the plan.

## Prerequisites

* An ImmyBot instance, such as `acme.immy.bot`, with your customers set up as **tenants**.
* An administrator in the Microsoft Entra tenant you sign in to ImmyBot with, to create an app registration.
* An ImmyBot administrator, to give that app a user and a role.

## How to connect

ImmyBot's API uses a Microsoft Entra app registration. You create it in your own Entra tenant, then let it into ImmyBot.

**1. Create the app registration**

In the Microsoft Entra admin center of the tenant you sign in to ImmyBot with, open **App registrations** and click **New registration**. Name it (for example, Rallied ImmyBot), keep **Single tenant only** as the supported account type, leave the redirect URI empty and click **Register**. On the app's **Overview**, copy the **Application (client) ID** and the **Directory (tenant) ID**.

**2. Create a client secret**

On the app, open **Certificates & secrets** and click **New client secret**. Copy its **Value**, not its **Secret ID**. Entra shows the value only once.

**3. Copy the app's Object ID**

Open **Enterprise applications**, find the same app and copy its **Object ID**. This is a different ID from the app registration's.

**4. Add the app as a person in ImmyBot**

In ImmyBot, open **Settings → People** and click **New**. Enter a first name, a last name and an email (ImmyBot requires one; any label works, such as `immybot-api@yourdomain.com`), paste the Object ID into **Azure Object ID**, and click **Create**.

**5. Make that person a user with a role**

Open **Settings → Users & Roles** and click **Add New User**. Select the person you created and click **Create Users**. Under **Direct Role Assignments**, give it a role that can see every tenant and run scripts, such as **System Administrator (Legacy)**, and click **Assign**.

**6. Connect ImmyBot**

In Rallied, go to **Settings → Integrations**, find the ImmyBot card and click **Connect**. Enter your **ImmyBot instance** (`acme` for `https://acme.immy.bot`), the **Directory (tenant) ID**, the **Application (client) ID** and the **Client secret**, and click **Connect**. The card shows **Connected** when it's ready.

Rallied checks the credentials with Microsoft Entra, then checks that ImmyBot accepts the app and that its role can list your tenants. If ImmyBot doesn't accept the app yet, recheck steps 4 and 5.

> [!WARNING]
>
> The client secret expires on the date you chose in Entra. When it expires, the agent can't reach ImmyBot until you create a new secret and reconnect with it.

## Mapping tenants to clients

When you connect, and once a day after that, Rallied syncs the tenants in your ImmyBot instance. A tenant Rallied can't link by itself waits for you: click **Match companies** at the top of the integration's detail page and pick its client. The **Companies** tab lists the linked tenants. Click **Sync from ImmyBot** there to pick up tenants you've added since.

Rallied doesn't list:

* Your own MSP tenant. It's never a client.
* Inactive tenants, or tenants marked for deletion. If a tenant is missing, check that it's active in ImmyBot, then sync again.

A tenant links to a client by itself when it has the same name as one of your clients, or a similar name plus the same Microsoft 365 tenant. When only the Microsoft 365 tenant matches, Rallied suggests the client and you confirm it.

On a client's ticket, the agent reads and changes only that client's tenant. It fills in the tenant ID automatically. A computer or session of another tenant is answered as not found.

In the MSP admin [Chat](https://docs.rallied.ai/dashboard/chat.md), the agent can also list every tenant and work on any of them, your own included. End users can't run any ImmyBot tool.

## How the agent uses it

A typical "my computer is missing an app" ticket goes like this. The agent:

1. Finds the computer by name, serial number or user, and checks whether it's online.
2. Reads what ImmyBot says needs attention and the latest result of each maintenance item, then the logs of the session that failed.
3. Searches your ImmyBot software library for the app.
4. Proposes installing it on that computer and waits for a technician's approval.
5. After approval, starts the deployment and notes the ImmyBot session on the ticket.
6. Comes back on its own to check the session, then reports the result and finishes the ticket.

ImmyBot runs a deployment in the background, so the agent checks the session again after a minute, then at longer intervals. If the session still hasn't finished an hour after it started, the agent stops checking, says so in an internal note and leaves it to a technician.

Every deployment or task run the agent starts suppresses reboots, sends the user no email, and skips the computer if it's offline.

### Running PowerShell

When the read tools and your library can't answer or fix the problem, the agent can propose a PowerShell script it wrote. The script runs on that one computer, as SYSTEM, and the agent gets its output back. It never runs on the ImmyBot server.

* Every script needs a technician's approval, even when you set the tool to **Auto**, and a [workflow](https://docs.rallied.ai/dashboard/workflows.md) can't approve it in advance.
* The approval shows the full script and a [script analysis](https://docs.rallied.ai/agents/execute-mode.md#script-analysis-on-approval-plans) of what it reads and changes.
* A script stops after 60 seconds.

## Limits

* The agent installs an app, or updates it to the latest version. To install a specific older version, use ImmyBot.
* The agent doesn't uninstall software, run tasks that take parameters, onboard computers or move them between tenants. A technician does those in ImmyBot.
* The agent doesn't create or change deployments. It reads the deployments made for a client's tenant only, not those that target several tenants.
* A session can be re-run only when it maintains one item, not a full maintenance or onboarding run, and its own settings suppress reboots, install no Windows updates, email no one, skip offline computers and reach no other tenant. Otherwise the agent deploys the app or runs the task again instead.

## Tools

To change a default, open the **Policies** tab on **Settings → Integrations → ImmyBot**. See [Approval settings](https://docs.rallied.ai/dashboard/policies.md).

| Tool | Default policy | Description |
| - | - | - |
| `immybot-list-computers` | Auto | List a client's computers, with search by name, user or serial |
| `immybot-get-computer` | Auto | Read one computer: OS, end of life, Windows 11 readiness, last Windows Update |
| `immybot-get-computer-status` | Auto | Check whether a computer's ImmyBot agent is connected |
| `immybot-list-computer-software` | Auto | List the software ImmyBot detected on a computer |
| `immybot-list-computer-events` | Auto | Read a computer's ImmyBot timeline |
| `immybot-get-computer-attention` | Auto | See what needs attention on a computer and its latest maintenance results |
| `immybot-list-sessions` | Auto | List a client's maintenance sessions |
| `immybot-get-session` | Auto | Read one session's status, actions and phases |
| `immybot-get-session-logs` | Auto | Read a session's logs |
| `immybot-search-software` | Auto | Search your software library for an app a client can receive |
| `immybot-search-maintenance-tasks` | Auto | Search your maintenance-task library |
| `immybot-list-deployments` | Auto | List the deployments made for a client's tenant |
| `immybot-list-tenants` | Auto | List every tenant in your instance. Admin chat only |
| `immybot-start-computer-reinventory` | Approval needed | Refresh a computer's software and inventory data |
| `immybot-deploy-software` | Approval needed | Install or update one library app on one computer |
| `immybot-run-maintenance-task` | Approval needed | Run one library task without parameters on one computer |
| `immybot-restart-session` | Approval needed | Re-run one computer's session when its settings are safe |
| `immybot-stop-session` | Approval needed | Cancel a running or pending session |
| `immybot-run-powershell` | Approval needed (always) | Run a PowerShell script the agent wrote on one computer and return its output |

## See also

* [Approval settings](https://docs.rallied.ai/dashboard/policies.md)
* [Execute Mode](https://docs.rallied.ai/agents/execute-mode.md)
* [Chat](https://docs.rallied.ai/dashboard/chat.md)
* [Integrations overview](https://docs.rallied.ai/integrations/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.