Metadata-Version: 2.4
Name: openclaw-secure
Version: 0.1.0
Summary: Secure mode switcher for OpenClaw - runs your existing installation in a sandboxed Docker container
Project-URL: Homepage, https://github.com/openclaw/openclaw-secure
Project-URL: Documentation, https://github.com/openclaw/openclaw-secure#readme
Project-URL: Repository, https://github.com/openclaw/openclaw-secure
Project-URL: Issues, https://github.com/openclaw/openclaw-secure/issues
Author-email: Gerald Enrique Nelson Mc Kenzie <lordxmen2k@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,docker,isolation,openclaw,sandbox,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# OpenClaw Secure

[![PyPI version](https://badge.fury.io/py/openclaw-secure.svg)](https://pypi.org/project/openclaw-secure/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker Required](https://img.shields.io/badge/docker-required-blue.svg)](https://www.docker.com/products/docker-desktop/)

Run OpenClaw in a secure, sandboxed Docker container with automatic device pairing and dashboard access.

## Quick Start

### 1. Install Prerequisites

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/Mac) or Docker Engine (Linux)
- [Python 3.10+](https://www.python.org/downloads/)
- pip or pipx

### 2. Install openclaw-secure

```bash
# Using pipx (recommended - isolated environment)
pipx install openclaw-secure

# Using pip
pip install openclaw-secure
```

### 3. Enable Secure Mode

```bash
# Interactive mode (will ask for config path, port, etc.)
openclaw-secure enable

# Non-interactive mode (uses defaults)
openclaw-secure enable --yes

# With custom config location
openclaw-secure enable --config "G:\\MyProjects\\openclaw\\config"

# With custom port
openclaw-secure enable --port 8080

# Maximum security sandbox
openclaw-secure enable --sandbox maximum --yes
```

### What Happens

1. **Detects** your OpenClaw config (or lets you specify location)
2. **Preserves** all settings, API keys, and models
3. **Configures** sandbox mode and gateway binding
4. **Starts** container with port mapping
5. **Auto-approves** any pending devices
6. **Opens** browser with authenticated URL

### Dashboard Access

After enabling, the dashboard URL with token is displayed:

```
Click to open: http://127.0.0.1:18789/#token=...
```

Or get it later:
```bash
openclaw-secure dashboard --no-open
```

### Fresh Install Setup (No Existing OpenClaw)

If you don't have OpenClaw installed, `openclaw-secure` can create a fresh config.

#### Step 1: Enable Secure Mode

```bash
openclaw-secure enable --yes
```

When no config is detected, it will create a fresh one automatically (or ask you in interactive mode).

#### Step 2: Run Onboard Wizard

After the container starts, set up your API keys:

```bash
# Interactive setup (recommended for first time)
docker exec -it openclaw-secure openclaw onboard

# Or use exec command
openclaw-secure exec onboard
```

This wizard will guide you through:
- Adding your AI provider API keys (Anthropic, OpenAI, etc.)
- Setting your default model
- Configuring workspace preferences

#### Step 3: Verify Setup

```bash
# Check version
openclaw-secure exec --version

# List agents
openclaw-secure exec agents list

# Open dashboard to configure API keys via web UI
openclaw-secure dashboard
```

Or use Docker directly for interactive setup:
```bash
docker exec -it openclaw-secure openclaw onboard
```

### Running OpenClaw CLI Commands

Execute any OpenClaw command inside the secure container:

```bash
# List agents
openclaw-secure exec agents list

# Add an agent
openclaw-secure exec agents add my-agent

# Check OpenClaw version
openclaw-secure exec --version

# Run onboard wizard (interactive - use docker directly)
docker exec -it openclaw-secure openclaw onboard

# Run any command
docker exec openclaw-secure openclaw <command>
```

### Common CLI Commands

```bash
# Check version
openclaw-secure exec --version

# List agents
openclaw-secure exec agents list

# Create new agent
openclaw-secure exec agents add my-agent

# Run onboard wizard (interactive)
docker exec -it openclaw-secure openclaw onboard

# Check container logs
docker logs openclaw-secure --tail 50
```

### Device Management

```bash
# List devices
openclaw-secure devices --list

# Approve a pending device
openclaw-secure devices --approve <device_id>

# List with docker directly
docker exec openclaw-secure openclaw devices list

# Approve with docker directly
docker exec openclaw-secure openclaw devices approve <device_id>
```

### Disable Secure Mode

```bash
openclaw-secure disable
```

This stops the container and restores your previous OpenClaw setup.

## Commands

| Command | Description |
|---------|-------------|
| `enable` | Start secure container mode |
| `disable` | Return to normal mode |
| `status` | Check current mode |
| `dashboard` | Open dashboard in browser |
| `devices` | Manage device pairing |
| `exec` | Run OpenClaw CLI commands inside container |
| `doctor` | Run diagnostics |
| `emergency-restore` | Force recovery |

## Options

```bash
openclaw-secure enable [OPTIONS]

Options:
  --config PATH          Custom config directory
  --port INTEGER         Custom port (default: 18789)
  --sandbox [chat-only|maximum|none]  Sandbox mode
  --network [none|bridge]  Network mode
  --disable-device-auth  Skip device pairing (not recommended)
  --yes / -y            Non-interactive mode
  --no-backup           Skip backup creation
```

## Prerequisites

Before installing `openclaw-secure`, ensure you have the following installed:

### Required

| Software | Version | Purpose | Download |
|----------|---------|---------|----------|
| **Docker Desktop** | Latest | Container runtime | [docker.com](https://www.docker.com/products/docker-desktop/) |
| **Python** | 3.10+ | Runtime for openclaw-secure | [python.org](https://www.python.org/downloads/) |
| **pip** or **pipx** | Latest | Package installer | Included with Python |

### Optional (for fresh OpenClaw installs)

| Software | Purpose |
|----------|---------|
| **OpenClaw CLI** | Only needed if you want to run `openclaw` commands locally outside the container |

### Platform-Specific Notes

**Windows:**
- Docker Desktop with WSL2 backend recommended
- Run PowerShell or Command Prompt as Administrator if you encounter permission issues

**macOS:**
- Docker Desktop for Mac (Apple Silicon or Intel)
- May need to allow Docker in System Preferences > Security & Privacy

**Linux:**
- Docker Engine (Docker Desktop not required)
- Add your user to the `docker` group: `sudo usermod -aG docker $USER`
- Log out and back in for group changes to take effect

### Verify Installation

```bash
# Check Docker
docker --version
docker ps

# Check Python
python --version

# Check pip
pip --version
```

## How It Works

1. **Container**: Runs official `ghcr.io/openclaw/openclaw:latest` image
2. **Port Mapping**: Exposes port 18789 to localhost
3. **Volume Mounts**: 
   - Config directory (read-write for API key updates)
   - Workspace directory
   - Cache directory
4. **Gateway Binding**: Configures `0.0.0.0` binding for Docker compatibility
5. **Auto-pairing**: Automatically approves devices on startup

## Security Notes

- Config files remain editable on your host
- Device auth is enabled by default (disable with `--disable-device-auth`)
- Sandbox modes protect your system from AI-generated code
- Network is isolated (bridge mode) by default

## License

MIT
