> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/developers/developers/custom-add-ons.md).

# Custom add-ons

Your own code joins the platform as an [add-on](https://docs.heisenware.com/reference/functions/add-ons.md): a program that offers its classes on the bus, so that its functions appear in the [Functions explorer](https://docs.heisenware.com/app-builder/app-builder/functions.md) and go onto the Flowboard like the platform's own. You write a plain class; [VRPC](https://docs.heisenware.com/developers/developers/vrpc.md) does the rest. There is no API to learn.

Node.js is the usual choice, and the scaffold below is Node.js. Any language VRPC has a library for works: Python and C++ too.

## What the platform gives your program

Whether your code runs inside the platform or on your own machine, it gets the same four values and needs nothing else:

| Variable      | What it is                             |
| ------------- | -------------------------------------- |
| `HW_DOMAIN`   | the workspace, `<account>.<workspace>` |
| `HW_BROKER`   | the broker to connect to               |
| `HW_USERNAME` | a login of that workspace              |
| `HW_PASSWORD` | its password                           |

Your program starts a `VrpcAgent` with them, registers its classes, and serves. The agent name it chooses is the name the Functions explorer lists it under.

## Writing the class

An add-on is a small Node project of your own: a class, the VRPC agent that puts it on the bus, and a Dockerfile. What it needs from the platform is the four variables below; everything else is yours.

### The JSDoc is the interface

What you document is what a member sees. The platform reads your JSDoc and builds the executor from it: the description on hover, the inputs, the outputs.

* **Every `@param` becomes an input**, in the order of the signature. Its name and its type are what the member reads.
* **A dotted `@param` folds into its parent**: document `@param {Object} options` before `@param {string} options.mode`, or the dotted one is dropped and the member never sees it.
* **A `@param` of function type becomes a handler**: an input the backend calls back, with an output for each value it delivers.
* **`@returns {Registration}` makes the function an** [**event function**](https://docs.heisenware.com/developers/developers/vrpc.md#event-functions), one that keeps calling its handler until it is released. A name of `on` followed by a capital letter does the same. There is no third rule.
* **`@nosideeffects`** declares a function that changes nothing anyone could observe, which is what a read-only connection may call. See [Declare what changes nothing](https://docs.heisenware.com/developers/developers/vrpc.md#declare-what-changes-nothing).

Private and protected members stay off the bus. A class without documentation still works; its member just gets unnamed inputs and no description.

## Running it inside the platform

Build your Docker image, push it where the platform can pull it ([write to us](mailto:support@heisenware.com) for a private registry), and install it from the Functions explorer's **Install Extension** button, under **Custom Extension**, by its full image name. The platform starts a container of it, hands it the four values above, and mounts the workspace's shared files at `/shared`. Its login appears with the workspace's other [integrations](https://docs.heisenware.com/app-manager/app-manager/integrations.md).

Your classes are in the Functions explorer as soon as the container is up. Installing the same image again replaces the running container, which is how you bring a new version in.

{% hint style="warning" %}

#### Your own image needs your own server

On the Heisenware cloud only Heisenware's own images may be installed, because those servers are shared. **Custom Extension** works on a dedicated server and on a [self-hosted](https://docs.heisenware.com/self-hosting/self-hosting.md) platform; elsewhere the install is refused with "Own Docker images run on your own server only". Running the same image outside the platform always works.
{% endhint %}

Instances your classes create persist only if your code writes them down. The platform mounts the shared volume into your container, so VRPC's persistor writing under `/shared` is the usual way: the instances come back when the container restarts, and you find their files in the [Files explorer](https://docs.heisenware.com/app-builder/app-builder/files.md).

## Running it outside the platform

Useful when your code has to reach a local network, when it needs hardware the platform has not got, or when you are on the cloud and the image is your own. You run it; the platform sees an agent like any other.

Make a VRPC integration of the workspace for it: App Manager → [Integrations](https://docs.heisenware.com/app-manager/app-manager/integrations.md) → **Add** → VRPC client. It gives you a username and a password.

```bash
docker run -it \
  -e HW_DOMAIN=acme.default \
  -e HW_BROKER=mqtts://acme.heisenware.cloud \
  -e HW_USERNAME=agentRunner@acme.default \
  -e HW_PASSWORD=<the password> \
  myaccount/myimage:1.0.0
```

The connection is outbound only, so nothing has to be opened in your firewall.

Once it connects, the agent is in the App Manager's [Agents panel](https://docs.heisenware.com/app-manager/app-manager/agents.md) as an unmanaged agent: the platform shows its status and when it was last seen, but its software is yours to update.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/developers/developers/custom-add-ons.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
