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.

Configure Aquila

Configure aquila.yml in the project root. To keep the Sagittarius token out of the file, set AQUILA_BACKEND_TOKEN in the environment or a local .env file.

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

Configuration

Aquila reads aquila.yml from the working directory. Built-in defaults are used when the file is absent. Configuration values are read from this file, except that AQUILA_BACKEND_TOKEN can override dynamic_config.backend_token so the token can be injected as a secret.

Select a different configuration file with AQUILA_CONFIG_PATH:

AQUILA_CONFIG_PATH=/path/to/aquila.yml cargo run

The log_level setting controls the default log level. The standard RUST_LOG variable can still provide a more specific runtime filter, for example RUST_LOG=aquila::server=trace.

Common (Static + Dynamic)

YAML key	Description
`mode`	`static` loads local flows; `dynamic` synchronizes with Sagittarius.
`environment`	`development`, `staging`, or `production`.
`log_level`	Default application log filter.
`nats.url`	NATS server URL.
`nats.bucket`	NATS KV bucket used to store flows.
`grpc.host`	Aquila gRPC bind host.
`grpc.port`	Aquila gRPC bind port.
`grpc.health_service`	Enables the gRPC health service.
`runtime_status.not_responding_after_secs`	Heartbeat timeout before `not_responding`.
`runtime_status.stopped_after_not_responding_secs`	Additional timeout before `stopped`.
`runtime_status.monitor_interval_secs`	Heartbeat monitor interval.

Static Mode

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

YAML key	Description	Default
`static_config.flow_path`	Path to the flow JSON file loaded at startup.	`./flowExport.json`

Dynamic Mode

Set mode: dynamic to keep flows synchronized from Sagittarius.

YAML key	Environment override	Description	Default
`dynamic_config.backend_url`	—	URL of the Sagittarius instance Aquila connects to for flow and action updates.	`http://localhost:50051`
`dynamic_config.backend_token`	`AQUILA_BACKEND_TOKEN`	Token used by Aquila to authenticate with Sagittarius.	`default_session_token`
`dynamic_config.backend_unary_timeout_secs`	—	Timeout for unary Sagittarius RPCs.	`5`

Service Configuration File

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

The service configuration is optional. Aquila starts with an empty service configuration when AQUILA_SERVICE_CONFIG_PATH is unset. Load one independently with:

AQUILA_SERVICE_CONFIG_PATH=/path/to/service.configuration.json cargo run

The file defines:

Allowed runtime tokens
Allowed action tokens
Optional default action configurations

If the selected 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": []
}