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

# The shell and what it can reach

> When your organization allows it, agents can run commands on your Mac. You allow commands per chat, and every command runs in a sandbox that writes only to your read-and-write trusted folders and cannot read your keys, keychain or the rest of your home folder.

When your organization's [Desktop policy](https://docs.xpander.ai/desktop/admin.md#desktop-policy) allows the **Shell**, agents in your app conversations can run commands on your Mac, for example to run tests or a build in a project you trusted. The composer's laptop strip shows **Shell on**.

## Allow commands and file changes for a chat

The first time in a conversation that an agent wants to run a command, the app asks **Run a command?** and shows the full command. The first time it wants to write a file, it asks **Write a file?** and shows the path.

| Choice | What it means |
| - | - |
| **Not now** | The agent continues without it. |
| **Allow once** | Only this command or this file. |
| **Allow for this chat** | Commands, or file writes, in this conversation without asking again. |

![Run a command? dialog showing npm test -- --watch=false, with Not now, Allow once and Allow for this chat](https://mintcdn.com/xpanderai-099931d1/5kO48nCPjVxjKi_K/images/desktop/shell-run-command.png?fit=max\&auto=format\&n=5kO48nCPjVxjKi_K\&q=85\&s=f708550077f4ee76912f4f48751aabe6)

The first command in a conversation asks first. Shown with sample data.

Stopping a conversation, or a change in your organization's policy, makes every conversation ask again.

## What a command can reach

Every command runs in its own macOS sandbox, built for that command from your trusted folders:

| | A command can | A command cannot |
| - | - | - |
| **Your trusted folders** | Read every trusted folder; write in the ones you trusted **Read and write** | Write in a **Read only** folder |
| **The rest of your home folder** | Nothing | Read or write anything outside your trusted folders |
| **Secrets** | Nothing | Read SSH keys, cloud credentials, the keychain or app data, even inside a trusted folder |
| **The system** | Read the system and installed developer software (for example Xcode, Homebrew, Node, Python and Rust) | Change the system, control other apps, or start background services |
| **Temporary files** | Use its own temporary folder, removed when the command ends | Leave temporary files behind |
| **The network** | Download packages and call web services, when **Shell network** is on | Reach the network when **Shell network** is off |

**Shell network** is on by default. Your organization can turn it off for everyone (**Shell can reach the network** in the [Desktop policy](https://docs.xpander.ai/desktop/admin.md#desktop-policy)), and you can turn it off for your Mac in [Settings](https://docs.xpander.ai/desktop/settings.md) > **Shell & files**. With it off, commands still run, but cannot download anything or call a web service.

## When the shell does not run

* Your organization's policy turns the **Shell** off, or you turned **Shell commands** off in Settings.
* **Files** are off for this computer, in your organization's policy or in your own Settings. The shell works inside your trusted folders, so it is off too.
* No folder is trusted yet.
* Your organization's policy is read only: the shell is read only too, and cannot write anywhere.
* The computer cannot run commands safely, for example on Windows today. The strip then reads **Shell unavailable**, and agents work with your files directly. See [Where it runs](https://docs.xpander.ai/desktop.md#where-it-runs).

Each command your agent runs on your Mac is recorded with the command's outcome and duration, never the content of your files.


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