OpenClaw Sandboxed Agent

A secure, sandboxed AI agent that runs in an isolated Docker container with gated host access via Telegram.

---

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  TELEGRAM USER                                                   │
│  Sends message to @your_agent_bot                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  OPENCLAW GATEWAY (Host)                                         │
│  • Routes messages to correct agent                             │
│  • Manages multiple agents                                      │
│  • Handles authentication                                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  SANDBOXED AGENT (Docker Container)                              │
│  • Isolated filesystem (no host access)                         │
│  • Non-root user (1000:1000)                                    │
│  • Limited network (bridge mode)                                │
│  • Dropped capabilities (ALL caps dropped)                      │
│  • Read-only root filesystem                                    │
│  • Resource limits (2GB RAM, 256 processes)                     │
└─────────────────────────────────────────────────────────────────┘

Security Model

Default Mode (Sandboxed):

• All tool execution happens inside the Docker container
• No access to host files, credentials, or system
• Internet access allowed (for web search, APIs)
• Workspace is isolated to /workspace inside container

Elevated Mode (Gated):

• Temporarily bypasses sandbox for host access
• Only allowlisted Telegram users can activate
• Per-session (must re-enable after timeout/new session)
• Runs as your host user (not root)

---

Features

Feature	Description	Mode
Sandboxed Execution	All commands run in isolated Docker container	Default
Elevated Access	Gated host access for system tasks	/elevated full
Multi-Agent	Run multiple isolated agents on one gateway	Config
Telegram Integration	Control via Telegram bot interface	Always
Workspace Isolation	Each agent has separate workspace	Default
SSH Access	Connect to remote servers	Elevated
Docker Control	Manage containers from agent	Elevated
File Operations	Read/write files in workspace	Both
Web Search	Search internet for information	Default
Code Execution	Run Python, bash, etc.	Both

---

Quick Start

1. Deploy Your Agent

Follow AGENT_TEMPLATE.md to create and configure your agent.

2. Start Using

Message your bot on Telegram. The agent responds with AI-powered assistance.

3. Access Host When Needed

Use /elevated commands when you need host access.

---

Using Elevated Mode

What is Elevated Mode?

Elevated mode is a security gate that allows the sandboxed agent to execute commands on the host system instead of inside the Docker container.

Use it for:

• SSH to remote servers
• Docker management
• Accessing host files
• System administration
• Copying files between workspace and host

Security: Only configured Telegram users can activate it.

---

Elevated Commands

Command	Description
/elevated full	Enable full elevated mode
/elevated off	Disable elevated mode
/elevated	Check current status

---

Example Workflows

Example 1: Check Server Status

[You] /elevated full

[Agent] Elevated mode: enabled

[You] Run system check: uptime, free memory, disk usage, and docker status

[Agent] Here's your system status:
- Uptime: 3 days, 2 hours
- Memory: 4.2GB free / 16GB total
- Disk: 45% used
- Docker: 3 containers running

[You] /elevated off

Example 2: SSH to Remote Server

[You] /elevated full

[Agent] Elevated mode: enabled

[You] SSH to myserver and check nginx logs

[Agent] Connecting to myserver...
Last login: Mon Feb 24 10:32:11 2026

nginx error logs (last 20 lines):
2026/02/24 10:30:15 [notice] 1234#1234: signal 17 (SIGCHLD) received
...

[You] /elevated off

Example 3: Deploy Code from Workspace

[You] Write a Python script that monitors CPU usage and save it as cpu_monitor.py

[Agent] Created cpu_monitor.py with CPU monitoring functionality.

[You] /elevated full

[Agent] Elevated mode: enabled

[You] Copy cpu_monitor.py to ~/scripts/ and make it executable

[Agent] Done. Copied to ~/scripts/cpu_monitor.py and chmod +x applied.

[You] /elevated off

Example 4: Docker Management

[You] /elevated full

[Agent] Elevated mode: enabled

[You] Show me all running containers and their resource usage

[Agent] 
CONTAINER ID   NAME            CPU %   MEM USAGE
abc123         openclaw-sbx    0.2%    512MiB
def456         postgres        1.1%    256MiB

[You] Restart the postgres container

[Agent] Restarting postgres container... Done.

[You] /elevated off

Example 5: Backup Workspace

[You] /elevated full

[Agent] Elevated mode: enabled

[You] Create a backup of /workspace to ~/backups/agent-backup-$(date +%Y%m%d).tar.gz

[Agent] 
Creating backup...
Backup saved: ~/backups/agent-backup-20260224.tar.gz (45MB)

[You] List my backups

[Agent] 
Backups in ~/backups/:
- agent-backup-20260224.tar.gz  45MB  Feb 24 20:30
- agent-backup-20260223.tar.gz  42MB  Feb 23 20:15

[You] /elevated off

---

Security Model Comparison

┌────────────────────────────────────────────────────────────────┐
│  DEFAULT MODE (Sandboxed)                                      │
│  ─────────────────────────                                     │
│  Container:    openclaw-sandbox:bookworm-slim                  │
│  User:         1000:1000 (non-root)                            │
│  Filesystem:   Isolated (/workspace only)                      │
│  Network:      Bridge (internet OK)                            │
│  Host Access:  ❌ NONE                                         │
│  Tools:        Limited by allowlist                            │
│  Use for:      AI chat, file editing, web search, coding       │
└────────────────────────────────────────────────────────────────┘
                              │
                              │ /elevated full (allowed users only)
                              ▼
┌────────────────────────────────────────────────────────────────┐
│  ELEVATED MODE (Host Access)                                   │
│  ───────────────────────────                                   │
│  Container:    None (runs on host)                             │
│  User:         Your host user                                  │
│  Filesystem:   Full host access                                │
│  Network:      Host network                                    │
│  Host Access:  ✅ FULL (as your user)                          │
│  Tools:        All host tools available                        │
│  Use for:      SSH, Docker, system admin, file management      │
│  Duration:     Per-session (auto-off on timeout/new session)   │
└────────────────────────────────────────────────────────────────┘

---

Configuration

Who Can Use Elevated Mode?

In AGENT_TEMPLATE.md, set allowed users:

{
  "tools": {
    "elevated": {
      "enabled": true,
      "allowFrom": {
        "telegram": ["YOUR_TELEGRAM_USER_ID"]
      }
    }
  }
}

Find your Telegram ID: Message @userinfobot on Telegram.

---

Best Practices

✅ Do

• Use /elevated full only when needed
• Use /elevated off when finished
• Keep sensitive files in workspace (isolated)
• Verify commands before executing in elevated mode
• Use for automation: backup, deployment, monitoring

❌ Don't

• Leave elevated mode on permanently
• Share your Telegram account (others can use elevated)
• Run untrusted code in elevated mode
• Store secrets in workspace without encryption
• Forget to disable elevated when done

---

Troubleshooting

Problem	Solution
/elevated not recognized	Your Telegram ID not in allowFrom list
"Permission denied" in elevated	Command needs sudo, run sudo command
"Command not found"	Tool not installed on host system
Elevated mode stuck	Send /elevated off or start new chat
Can't SSH	Copy SSH key to workspace first, use /workspace/id_ed25519

---

What Makes This Secure?

1. Isolation by Default: All AI execution is sandboxed
2. Gated Elevation: Host access requires explicit user authorization
3. Per-Session: Elevated mode doesn't persist indefinitely
4. User Restrictions: Only configured users can elevate
5. Non-Root Container: Even in sandbox, runs as unprivileged user
6. Capability Dropping: Container has ALL Linux capabilities removed
7. Read-Only Root: Container filesystem cannot be modified

---

More Information

• Deployment Guide: See AGENT_TEMPLATE.md
• OpenClaw Docs: https://docs.openclaw.ai/
• Sandboxing: https://docs.openclaw.ai/gateway/sandboxing

---

Version: 2026.2.24
License: MIT