Skip to content
Ballastra
Open Ballastra

Aeros

Build on top of your community.

Aeros are Ballastra's bots: commands, interactive components, modals, rich embeds and event-driven workflows that a community can install without handing over the keys.

  1. 01Developer PortalCreate an Aero and copy its token once.
  2. 02Create AeroName it, describe it, request the permissions it needs.
  3. 03Install into a NexusSomeone with Manage Aeros adds it from Nexus settings.
  4. 04Managed roleThe install creates a role tied to the Aero.
  5. 05Bounded permissionsCategory and Space overrides apply to it like any member.

What is an Aero?

An Aero is a bot built on Ballastra. Developers create one in the Developer Portal, declare what it does, and publish it to the Aero directory. A Nexus installs it in one step.

Every install creates a managed role. The installer decides what is granted, can only grant permissions they hold themselves, and an Aero can never hold Manage Nexus, Manage Roles or Manage Aeros.

How Aeros run

You run an Aero’s code wherever you like. It connects to the Aero gateway for real-time events and calls the Aero REST API to act inside the Nexuses it is installed in.

Tokens are stored as SHA-256 hashes and shown exactly once; regenerating is the only way to get a new one.

Event delivery is best-effort today — build Aeros to tolerate a missed event.

What an Aero can do

Slash commands
Native commands with options and autocomplete, scoped to what a developer declares.
Message components
Buttons and select menus a member can press inside a message — every chosen value re-checked against the Nexus.
Modals
Server-validated forms an Aero can open, with single-submit handling and role-aware submission paths.
Rich embeds
Validated cards with title, description, fields, images, author and footer.
Workflows
Event-driven automation — when a member joins, a message is created, a role changes or an opportunity is posted, run conditions and actions automatically.
Scheduled automation
Workflows that run on a schedule, not just in reaction to an event.
App directory
A discoverable directory where a Nexus can browse and install Aeros with one step.
Scoped authorization
Installing an Aero grants it a managed role; every action re-checks install, scope and user permission.
Auto-suspend
Inactive or misbehaving Aeros pause themselves with a visible reason instead of silently breaking a Nexus.

Workflows

A workflow watches for a trigger, matches it against conditions and runs a set of actions — so common community chores happen without anyone typing a command.

  • Member joins. Greet them, assign a role, point them to the right Space.
  • Message created. Filter a Space by rules and route, flag or delete automatically.
  • Role changes. Run follow-up actions when someone is promoted or moved.
  • Scheduled. Post a weekly digest or prune stale threads on a timer.

Guardrails

A managed role, not a backdoor

When you install an Aero it receives a managed role, so the ordinary permission system applies to it unchanged. It can never hold the permissions that manage the Nexus, its roles or its Aeros.

Declared permissions

Commands and workflows declare what they need up front. Nothing runs with unrequested scope.

Auditable activity

Aero actions are logged per Nexus, so a community can see what automation did, when, and who triggered it.

Build or install

Developers start in the Developer Portal. If you run a Nexus, the Aero directory inside Ballastra is where you find automation worth installing.

Open the Developer PortalOpen Ballastra