Aquila Installation Guide

Use this guide to install and configure Aquila.

Use Docker Compose to run Aquila and related services. If you are developing Aquila locally, make sure the Aquila container is stopped to avoid port conflicts. If your compose setup supports profiles, you can set COMPOSE_PROFILES=ide to run only IDE-related services and start Aquila manually.

Virtual Development Environment (Preferred)

Use the shared environment setup from the main platform docs:

Visit Setup Guide

Manual Installation

Clone Aquila

Clone this repository to your local machine.

Set up environment variables

Configure .env in the project root with the required settings. You can use .env-example as a starting point.

Ensure required services are running

NATS:

Ensure a NATS instance is reachable
Enable JetStream
See NATS installation docs

Sagittarius:

Required for dynamic mode (MODE=dynamic)
Ensure the configured endpoint is reachable

Start Aquila

Run:

cargo run

Environment Variables

Aquila configuration is split into shared variables and mode-specific variables.

Common (Static + Dynamic)

Name	Description	Default
`MODE`	Runtime mode. `static` loads local flows. `dynamic` enables dynamic synchronization with Sagittarius.	`static`
`ENVIRONMENT`	Runtime environment (`development`, `staging`, `production`).	`development`
`NATS_URL`	URL of the NATS instance Aquila connects to.	`nats://localhost:4222`
`NATS_BUCKET`	Name of the NATS KV bucket used to store flows.	`flow_store`
`GRPC_HOST`	Hostname for the Aquila gRPC server.	`127.0.0.1`
`GRPC_PORT`	Port for the Aquila gRPC server.	`8081`
`WITH_HEALTH_SERVICE`	Enables the gRPC health service when set to `true`.	`false`
`SERVICE_CONFIG_PATH`	Path to the JSON service-configuration file used for runtime/action authorization and default action configs.	`./service.configuration.json`
`RUNTIME_STATUS_NOT_RESPONDING_AFTER_SECS`	Seconds before a runtime service is marked as `not_responding` when no heartbeat was received.	`90s`
`RUNTIME_STATUS_STOPPED_AFTER_NOT_RESPONDING_SECS`	Additional seconds before a non-responding runtime service is marked as `stopped`.	`180s`
`RUNTIME_STATUS_MONITOR_INTERVAL_SECS`	Interval in which runtime service heartbeats are checked.	`30s`
`SAGITTARIUS_UNARY_RPC_TIMEOUT_SECS`	Timeout in seconds for unary RPC calls from Aquila to Sagittarius.	`5s`

Static Mode

Set MODE=static to load flows from a local JSON file and insert them into the NATS KV store on startup.

Name	Description	Default
`FLOW_FALLBACK_PATH`	Path to the flow JSON file loaded at startup.	`./flowExport.json`

Dynamic Mode

Set MODE=dynamic to keep flows synchronized from Sagittarius.

Name	Description	Default
`SAGITTARIUS_URL`	URL of the Sagittarius instance Aquila connects to for flow and action updates.	`http://localhost:50051`
`RUNTIME_TOKEN`	Token used by Aquila to authenticate with Sagittarius.	`default_session_token`

Service Configuration File

To authorize services like Taurus, Draco, or an Action, they must be declared in Aquila's service configuration file.

SERVICE_CONFIG_PATH points to a JSON file that defines:

Allowed runtime tokens
Allowed action tokens
Optional default action configurations

This file is loaded on startup. If the file is missing or invalid, Aquila starts with an empty service configuration.

Default:

{
  "actions": [],
  "runtimes": [
    {
      "identifier": "taurus",
      "token": "HsCEzbCuaUtUGSCrvwsSbJSlS2HH6TrW0ZeEKUZGTiOH8vPEZxyAEOx974Ku72l4"
    },
    {
      "identifier": "draco-rest",
      "token": "SBO3dRKmhszmGH6KxpgKoYGp0gBfgWqV6WEiKtMxldyeWiYLqJx6vwLuVLKRhu8H"
    },
    {
      "identifier": "draco-cron",
      "token": "VuTFgCj1PO6yr8smk43XLmeTUtlyKa2wjA0zvmz7WZDtgfXC62Ypd1b8fjJl8HvI"
    }
  ]
}

You can add as many runtimes as needed. To add an Action, add an entry under actions. To provide default Action-level config, add configs entries for that action.

{
  "actions": [
    {
      "token": "action_token",
      "identifier": "discord",
      "configs": [
        {
          "project_id": 1,
          "configs": [
            {
              "identifier": "send_message",
              "value": {
                "channel_id": "123456789012345678",
                "content": "Hello from bot"
              }
            }
          ]
        }
      ]
    }
  ],
  "runtimes": []
}