# AstrBot Agent Sandbox Security Measures Against Malicious Hosts

> Discover AstrBot's Agent Sandbox security measures like command filtering, filesystem confinement, and container isolation protecting against malicious hosts. Learn how AstrBot ensures safe execution.

- Repository: [AstrBot AI/AstrBot](https://github.com/AstrBotDevs/AstrBot)
- Tags: security
- Published: 2026-03-12

---

**AstrBot's Agent Sandbox employs a defense-in-depth architecture that combines local command filtering, filesystem path confinement, and remote container isolation with token authentication to prevent malicious hosts from executing harmful operations.**

AstrBot is an open-source multi-platform chatbot framework developed by AstrBotDevs. Its Agent Sandbox provides isolated execution environments for agent-requested code and shell commands, implementing robust **AstrBot Agent Sandbox security measures against malicious hosts** through layered protections that restrict both command execution and filesystem access.

## Local Sandbox Protections (LocalBooter)

The default `LocalBooter` in [`astrbot/core/computer/booters/local.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/local.py) implements two critical safety layers for host-level protection: command filtering and path confinement. These measures ensure that even if an agent generates malicious instructions, the local execution environment remains contained.

### Command Filtering with Blocked Patterns

The `_is_safe_command()` function validates all shell commands against a static denylist `_BLOCKED_COMMAND_PATTERNS`. This list includes dangerous operations like recursive deletion (`rm -rf`), disk formatting (`mkfs`), system shutdown commands, and fork bombs.

```python

# astrbot/core/computer/booters/local.py

_BLOCKED_COMMAND_PATTERNS = [
    " rm -rf ",
    " rm -fr ",
    " rm -r ",
    " mkfs",
    " dd if=",
    " shutdown",
    " reboot",
    " poweroff",
    " halt",
    " sudo ",
    ":(){:|:&};:",
    " kill -9 ",
    " killall ",
]

def _is_safe_command(command: str) -> bool:
    cmd = f" {command.strip().lower()} "
    return not any(pat in cmd for pat in _BLOCKED_COMMAND_PATTERNS)

```

Any attempt to execute a blocked command raises `PermissionError` in `LocalShellComponent.exec`, preventing destructive operations before they reach the operating system.

### Filesystem Path Confinement

The `_ensure_safe_path()` function restricts all file operations to three trusted roots: `astrbot_root`, `astrbot_data_path`, and `astrbot_temp_path`. This prevents agents from accessing sensitive system files or other user data outside the AstrBot environment.

```python

# astrbot/core/computer/booters/local.py

def _ensure_safe_path(path: str) -> str:
    abs_path = os.path.abspath(path)
    allowed_roots = [
        os.path.abspath(get_astrbot_root()),
        os.path.abspath(get_astrbot_data_path()),
        os.path.abspath(get_astrbot_temp_path()),
    ]
    if not any(abs_path.startswith(root) for root in allowed_roots):
        raise PermissionError("Path is outside the allowed computer roots.")
    return abs_path

```

All filesystem operations—including `create_file`, `read_file`, `write_file`, `delete_file`, and `list_dir`—invoke this helper, ensuring that paths like `/etc/passwd` or system directories are inaccessible to agent processes.

## Remote Sandbox Isolation (ShipyardBooter)

For high-risk environments or untrusted agent code, `ShipyardBooter` in [`astrbot/core/computer/booters/shipyard.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/shipyard.py) provides hardware-level isolation via the Shipyard/Shipyard-Neo platform. This remote sandbox architecture ensures that malicious code runs in ephemeral containers completely separated from the host machine.

### Token-Based Authentication

The `ShipyardClient` requires bearer token authentication for all API interactions. The `ShipyardBooter` initializes the client with an `access_token` from the configuration, ensuring only the authenticated AstrBot instance can spawn and control sandbox containers.

```python

# astrbot/core/computer/booters/shipyard.py

class ShipyardBooter(ComputerBooter):
    def __init__(self, endpoint_url: str, access_token: str, ttl: int = 3600,
                 session_num: int = 10) -> None:
        self._sandbox_client = ShipyardClient(
            endpoint_url=endpoint_url, access_token=access_token
        )
        ...

```

This token-based approach prevents unauthorized entities from accessing the remote sandbox API, even if the endpoint URL is discovered.

### Health Check Validation

Before reusing any remote container, the `available()` method performs proactive health checks via `get_ship()`. If the container reports `status != 1` or returns no data, it is marked unhealthy and discarded, preventing persistence of compromised environments.

```python

# astrbot/core/computer/booters/shipyard.py

async def available(self) -> bool:
    try:
        ship_id = self._ship.id
        data = await self._sandbox_client.get_ship(ship_id)
        if not data:
            logger.info("[Computer] Shipyard sandbox health check: id=%s, healthy=False (no data)", ship_id)
            return False
        health = bool(data.get("status", 0) == 1)
        logger.info("[Computer] Shipyard sandbox health check: id=%s, healthy=%s", ship_id, health)
        return health
    except Exception as e:
        logger.error(f"Error checking Shipyard sandbox availability: {e}")
        return False

```

This validation ensures that each agent session runs in a verified clean environment, eliminating the risk of cross-contamination from previous malicious executions.

## Configuration Audit and Validation

The dashboard route in [`astrbot/dashboard/routes/config.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/dashboard/routes/config.py) implements `_compare_and_log_sandbox_changes()` to audit all configuration modifications. When users modify sandbox settings, the system logs the specific changes with old and new values, creating an immutable record of security-critical configuration drift.

```python

# astrbot/dashboard/routes/config.py

def _compare_and_log_sandbox_changes(old_ps, new_ps):
    old_sandbox = old_ps.get("sandbox", {})
    new_sandbox = new_ps.get("sandbox", {})
    ...
    logger.info("[Computer] Config changed: sandbox.%s %s -> %s", key, old_val, new_val)

```

Only configurations passing validation (requiring valid `endpoint_url` and `access_token` for remote mode) activate the Agent Sandbox, preventing accidental exposure of insecure sandbox settings.

## Summary

- **Command Filtering**: Static denylist blocks dangerous shell patterns including `rm -rf`, `mkfs`, and fork bombs via `_is_safe_command()` in [`local.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/local.py).
- **Path Confinement**: Filesystem operations restricted to AstrBot directories via `_ensure_safe_path()`, preventing access to system files like `/etc/passwd`.
- **Remote Isolation**: Shipyard containers provide hardware-level separation with token-authenticated API access via `ShipyardBooter`.
- **Health Monitoring**: Proactive container validation via `available()` prevents reuse of compromised remote environments.
- **Audit Logging**: Configuration changes tracked via `_compare_and_log_sandbox_changes()` ensure accountability for security settings.

## Frequently Asked Questions

### What shell commands are blocked by AstrBot's local sandbox?

The local sandbox blocks commands containing dangerous patterns defined in `_BLOCKED_COMMAND_PATTERNS` within [`astrbot/core/computer/booters/local.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/local.py). Blocked patterns include recursive deletion commands (`rm -rf`, `rm -fr`), disk formatting (`mkfs`), direct disk writes (`dd if=`), system shutdowns (`shutdown`, `reboot`, `poweroff`), privilege escalation (`sudo`), fork bombs (`:(){:|:&};:`), and process termination utilities (`kill -9`, `killall`). The `_is_safe_command()` function converts commands to lowercase and checks for these substrings, raising `PermissionError` if any match is found.

### How does AstrBot prevent agents from escaping the sandbox directory?

AstrBot enforces filesystem isolation through the `_ensure_safe_path()` function in [`astrbot/core/computer/booters/local.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/local.py). This function resolves all paths to absolute form and verifies they start with one of three trusted roots: `astrbot_root`, `astrbot_data_path`, or `astrbot_temp_path`. If a requested path falls outside these directories—such as system paths like `/etc/passwd` or `/root/`—the function raises `PermissionError` with the message "Path is outside the allowed computer roots." All file operations including `create_file`, `read_file`, `write_file`, and `delete_file` invoke this validation helper.

### What authentication protects the remote Shipyard sandbox?

The remote Shipyard sandbox uses bearer token authentication implemented in [`astrbot/core/computer/booters/shipyard.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/shipyard.py). The `ShipyardBooter` class initializes a `ShipyardClient` with an `access_token` parameter sourced from the AstrBot configuration. This token must be included in all API requests to the remote sandbox endpoint. The authentication ensures that even if the endpoint URL is exposed, unauthorized entities cannot spawn containers or execute code within the AstrBot sandbox environment. Configuration validation requires both `endpoint_url` and `access_token` before enabling remote sandbox mode.

### How does AstrBot verify remote sandbox containers are secure before reuse?

AstrBot implements proactive health checking through the `available()` method in [`astrbot/core/computer/booters/shipyard.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/computer/booters/shipyard.py). Before reusing an existing container for agent execution, this method queries the remote ship via `get_ship()` and validates that the returned data contains `status == 1`. If the container reports any other status, returns no data, or raises an exception, the method returns `False` and the `ShipyardBooter` discards the unhealthy container. This prevents the reuse of potentially compromised or corrupted environments, ensuring each agent session runs in a verified clean state.