Launch Plugin Badge

Build a no-code /launch link, HTML button, or README badge that opens an OpenHands conversation with your plugin pre-loaded — no API key in the URL.

Source: launch-plugin-badge/

The OpenHands frontend has a /launch route that anyone can click. It decodes a plugins parameter, shows a confirmation modal, and — after the user confirms — calls POST /api/v1/app-conversations using the user’s own auth. No secrets in the URL.

This is the no-code equivalent of Load a Plugin: instead of writing Python to call the API, you construct a URL and put it in a README badge or an HTML button.

The URL Format

https://app.all-hands.dev/launch?plugins=<BASE64>&message=<URL-ENCODED>

Parameter	Format	Purpose
plugins	Base64-encoded JSON array of plugin specs	Which plugins to load
message	URL-encoded string	Initial message sent to the agent

Building the URL

1. Define Your Plugin Spec

   plugins = [
       {
           "source": "github:your-org/your-repo",
           "ref": "main",
           "repo_path": "path/to/plugin-dir",
       }
   ]
   
2. Base64-Encode It

   import base64
   import json
   
   encoded = base64.b64encode(json.dumps(plugins).encode()).decode()
   
3. URL-Encode the Message

   from urllib.parse import quote
   
   message = "/my-plugin:run"
   encoded_message = quote(message)
   
4. Assemble the URL

   url = f"https://app.all-hands.dev/launch?plugins={encoded}&message={encoded_message}"
   

Turn It Into a Badge

Once you have the URL, wrap it in Markdown or HTML:

Markdown badge

[![Open with my plugin](https://img.shields.io/badge/Open%20with%20my%20plugin-blue)](YOUR_LAUNCH_URL)

HTML button

<a href="YOUR_LAUNCH_URL">
  <button>Open with my plugin</button>
</a>

Plain link

[Open with my plugin](YOUR_LAUNCH_URL)

Use the Generator Script

The example ships a script that builds and prints these for you:

python build_launch_url.py \
    --source github:your-org/your-repo \
    --repo-path path/to/plugin-dir \
    --message "/my-plugin:run" \
    --label "Try my plugin"

No API key needed — this only constructs URLs.

Parameterized Plugins

If your plugin declares parameters in its manifest, they appear as editable inputs in the launch confirmation modal:

plugins = [
    {
        "source": "github:your-org/your-repo",
        "ref": "main",
        "repo_path": "my-plugin",
        "parameters": {
            "environment": "staging",   # Pre-fills the input; user can change it
        },
    }
]

See Also

• Load a Plugin — The programmatic (Python) equivalent of this example
• Plugins — Full plugin documentation including how to create a plugin manifest