> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Launcher

> Use the OpenHands Cloud `/launch` route to open a conversation with plugins or skills pre-configured from a Git repository.

The OpenHands Cloud `https://app.all-hands.dev/launch` route lets you create shareable links that open OpenHands with one or more plugins already selected.

This is useful for:

* adding a "Try it" link or badge to a plugin README
* sharing a pre-configured plugin in docs, issues, or Slack
* building internal test pages for plugin development

<Note>
  `/launch` is a Cloud route, not a standalone REST endpoint. After the user opens the link and confirms the plugin configuration, OpenHands starts a conversation using the normal V1 conversation flow described in the [Cloud API guide](/openhands/usage/cloud/cloud-api).
</Note>

## Before You Start

You will need:

* an OpenHands Cloud account
* a plugin or skill stored in a Git repository
* the repository source, and optionally a branch/tag/commit and subdirectory path

<Warning>
  Only share plugins and skills from sources you trust. The launch flow asks the user to trust the extension before it runs with the agent secrets configured in their account.
</Warning>

## Step 1: Define the Plugin

Create a JSON array of plugin definitions. Each item uses this shape:

```json theme={null}
[
  {
    "source": "github:OpenHands/extensions",
    "ref": "main",
    "repo_path": "plugins/pr-review"
  }
]
```

The fields are:

* `source` - where the plugin lives, such as `github:owner/repo` or a Git URL
* `ref` - optional branch, tag, or commit
* `repo_path` - optional subdirectory inside the repository
* `parameters` - optional configuration values that OpenHands shows as editable inputs before launch

<Note>
  The same format works for skills. For example, a skill in the OpenHands extensions repo would use `"repo_path": "skills/github"`.
</Note>

## Step 2: Encode the Plugin Definition

The `plugins` query parameter must be a base64-encoded version of your JSON array.

```json theme={null}
[
  {
    "source": "github:OpenHands/extensions",
    "ref": "main",
    "repo_path": "plugins/pr-review"
  }
]
```

Convert that JSON into base64-encoded text, then use the encoded value as the `plugins` query parameter in your `/launch` URL.

## Step 3: Add an Optional Starting Message

If you want the launched conversation to start with a prompt, add a `message` query parameter.

```text theme={null}
https://app.all-hands.dev/launch?plugins=W3sic291cmNlIjoiZ2l0aHViOk9wZW5IYW5kcy9leHRlbnNpb25zIiwicmVmIjoibWFpbiIsInJlcG9fcGF0aCI6InBsdWdpbnMvcHItcmV2aWV3In1d&message=/pr-review%20https%3A//github.com/OpenHands/OpenHands/pull/12699
```

In this example:

* `plugins` loads the `pr-review` plugin from `OpenHands/extensions`
* `message` pre-fills the initial task for the conversation

## Step 4: Open the Launch URL

When someone opens the link in OpenHands Cloud:

1. They sign in if needed.
2. OpenHands shows the plugins or skills from the URL.
3. Any `parameters` values are shown as inputs that the user can review or edit.
4. The user confirms they trust the extension.
5. OpenHands starts the conversation with the selected plugin configuration.

## Simple Format for Development

For quick local or staging tests, you can use simpler query parameters instead of base64 encoding:

```text theme={null}
https://app.all-hands.dev/launch?plugin_source=github:OpenHands/extensions&plugin_ref=main&plugin_repo_path=plugins/pr-review
```

This format is convenient for manual testing, but the encoded `plugins` format is better for production links because it also supports multiple plugins in one URL.

## Next Steps

* Use the [Cloud API guide](/openhands/usage/cloud/cloud-api) for authentication and conversation lifecycle details.
* See the [REST API (V1) overview](/openhands/usage/api/v1) for the V1 endpoints behind Cloud conversations.