Skip to content
Ballastra
Open Ballastra

Aero developer docs

Aero developer docs

Build an Aero: an app that lives inside a Nexus, reacts to events, answers commands and acts through the permissions a Nexus owner grants. Your Aero runs wherever you host it and talks to two things: the realtime gateway and the runtime API.

Overview

Three steps to a working Aero:

  1. Create an Aero in the Developer Portal and copy its token (shown once).
  2. Declare which events it listens to, and register any slash commands.
  3. Run your client: connect to the gateway, handle events and commands, and act through the runtime API.

A Nexus owner then installs your Aero and grants it permissions. Your Aero never has more authority than the role those grants create, and every action is checked on the server against it.

Use the SDK (recommended)

The official @ballastra/aero package does the boring parts for you: connecting, re-registering on reconnect, de-duplicating deliveries, and typed helpers. Most Aeros are a few lines with it.

Install
npm install @ballastra/aero
A whole Aero, with the SDK
import { createAero } from '@ballastra/aero';

const aero = await createAero({ token: process.env.AERO_TOKEN });

aero.on('member.joined', async (ev) => {
  const m = ev.data.member;
  if (m.is_aero) return;
  await aero.sendMessage(ev.nexus_id, process.env.WELCOME_SPACE_ID, `Welcome, ${m.name}! 👋`);
});

aero.command('welcome', async (i) => {
  await i.reply(`Welcome, ${i.options.name || i.invoker.name}! 👋`);   // reply() posts into the space
});

Want to see exactly what it does underneath? The rest of these docs describe the raw contract the SDK is built on, which you can also use directly.

Authentication

Every runtime request carries your token in the Authorization header, using the Aero scheme:

HTTP header
Authorization: Aero <your-token>

The token is shown once when you create or rotate the Aero. Store it as a secret, such as an environment variable, never in client-side code or a public repo. Rotating it in the portal immediately invalidates the old one.

Where to go next