OpenHands

Cygnal Analyzer for OpenHands

OpenHands is a powerful platform for AI software development agents that can modify code, run commands, browse the web, and interact with APIs.

Getting Started

To get started with the Cygnal security analyzer:

1. Create Gray Swan Account

1. Navigate to the Gray Swan platform and create an account if you don't already have one
2. Create a Gray Swan API key from your account settings

2. Configure OpenHands

Configure OpenHands to use the Cygnal analyzer using either the Settings UI (see Configure via Settings UI below) or by adding the following to your config.toml file.

The config.toml file can be located in:

• Current directory: ./config.toml
• User config directory: ~/.openhands/config.toml

[security]
security_analyzer = "grayswan"

3. Run OpenHands

Choose one of the following methods to run OpenHands with Cygnal security:

Option A: CLI Launcher (Recommended)

1. Set environment variables:

   # Required: Your Gray Swan API key
   export GRAYSWAN_API_KEY="your-grayswan-api-key-here"
   
   # Optional: Your Gray Swan policy ID (if using custom policies)
   export GRAYSWAN_POLICY_ID="your-policy-id"

2. Install uv (if you haven't already): See the uv installation guide for your platform.

3. Launch OpenHands:

   # Launch the GUI server (recommended)
   uvx --python 3.12 --from openhands-ai openhands serve
   
   # Or launch the CLI
   uvx --python 3.12 --from openhands-ai openhands

   You'll find OpenHands running at http://localhost:3000 (for GUI mode)!

Option B: Docker

Run OpenHands with Gray Swan security using Docker (API credentials are passed directly to the container):

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -e GRAYSWAN_API_KEY="your-grayswan-api-key-here" \
    -e GRAYSWAN_POLICY_ID="your-policy-id" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/.openhands \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.55

Replace the placeholder values:

• "your-grayswan-api-key-here" → your actual Gray Swan API key
• "your-policy-id" → your policy ID from Step 2 (or remove this line entirely if using default protections)

Configure via Settings UI

Instead of editing the config.toml file, you can configure the Cygnal analyzer through the OpenHands web interface:

1. Start OpenHands using either method above (it will run at http://localhost:3000)
2. Open the OpenHands settings interface
3. Select "Cygnal by Gray Swan AI" from the security analyzer dropdown
4. This works with both CLI and Docker installations

Verification

To verify that Cygnal protection is active:

1. Check OpenHands logs for Cygnal security analyzer initialization and activity. Look for messages like:

   GraySwanAnalyzer initialized with history_limit=20, timeout=30s
   Using GraySwan policy ID from environment: your-policy-id
   Event stream set for GraySwanAnalyzer
   Sending request to GraySwan API with X messages and policy_id: your-policy-id

2. Monitor your dashboard at platform.grayswan.ai/activity to see:

   • Agent requests being logged in real-time
   • Policy evaluations and results
   • Any security violations or alerts

3. Test the integration by having your agent perform a simple task. You should see the activity appear in your Gray Swan dashboard within a few moments.