Getting Started

Table of Contents

  1. Prerequisites
  2. Quick Installation
    1. From Crates.io
    2. From Binary Release
    3. From Source
    4. Build Dashboard (Optional)
  3. First Run: Provision an Admin
  4. Configuration
    1. Command-Line Flags
    2. Environment Variables
  5. Verify Installation
    1. Check Server Status
    2. Test Query
    3. Access Dashboard
  6. Using the CLI
  7. Using the Client SDK
    1. Rust
    2. Python
    3. JavaScript
  8. PM2 Deployment (Production)
  9. Next Steps

Prerequisites

Before installing Aegis-DB, ensure you have:

  • Rust 1.85+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
  • Trunk (for dashboard): cargo install trunk

No OpenSSL or libssl-dev is needed: all TLS uses rustls.

Quick Installation

From Crates.io

# Install server
cargo install aegis-server

# Install CLI
cargo install aegisdb-cli

From Binary Release

# Download the latest release binary and its checksums (v0.6.0)
curl -LO https://github.com/AutomataNexus/Aegis-DB/releases/download/v0.6.0/aegis-server-v0.6.0-linux-x86_64
curl -LO https://github.com/AutomataNexus/Aegis-DB/releases/download/v0.6.0/SHA256SUMS.txt
sha256sum --check --ignore-missing SHA256SUMS.txt

# Run server (default 127.0.0.1:9090)
chmod +x aegis-server-v0.6.0-linux-x86_64
./aegis-server-v0.6.0-linux-x86_64 --data-dir ./data

From Source

# Clone the repository
git clone https://github.com/AutomataNexus/Aegis-DB.git
cd Aegis-DB

# Build release
cargo build --release --workspace

# Run server (default 127.0.0.1:9090)
./target/release/aegis-server --data-dir ./data

Build Dashboard (Optional)

cd crates/aegis-dashboard
trunk build --release

First Run: Provision an Admin

As of v0.3.1 the server is fail-closed: with no users configured it returns 503 on authenticated routes (only /health and /api/v1/auth/login stay open) until you provision an admin. Set the admin credentials before starting, and they are persisted on first boot:

export AEGIS_ADMIN_USERNAME=admin
export AEGIS_ADMIN_PASSWORD=your_secure_password
./aegis-server

If you need the legacy behavior where reads are served to anonymous callers while no users exist (e.g. an internal proxy that talks to Aegis-DB unauthenticated), opt in explicitly — every such request is logged as a security warning:

export AEGIS_OPEN_BOOTSTRAP=true

Configuration

The server is configured with command-line flags plus a few environment variables. Run aegis-server --help for the full list.

Command-Line Flags

Flag Description Default
-H, --host Bind address 127.0.0.1
-p, --port Server port 9090
-d, --data-dir Data directory; enables disk persistence (in-memory)
--node-id / --node-name Node identity in a cluster auto-generated
--peers Comma-separated peer addresses to join (none)
--cluster Cluster name aegis-cluster
--tls, --tls-cert, --tls-key Enable HTTPS with PEM cert and key off
--cluster-tls, --cluster-ca-cert TLS / mTLS for cluster traffic off

Environment Variables

Variable Description Default
AEGIS_ADMIN_USERNAME / AEGIS_ADMIN_PASSWORD Admin provisioned on first boot (none)
AEGIS_TLS_CERT / AEGIS_TLS_KEY TLS cert / key paths when the flags are not given (none)
AEGIS_PRODUCTION Production mode (requires TLS unless AEGIS_ALLOW_INSECURE) false
AEGIS_CORS_ORIGINS Comma-separated allowed CORS origins (none)
AEGIS_TS_HOT_DAYS Time-series days kept in RAM 7
AEGIS_TS_COLD_DAYS Time-series days kept in the on-disk cold tier (0 disables) 365
AEGIS_TS_MAX_QUERY_POINTS Most points one time-series query may return 2000000
RUST_LOG Log filter (e.g. info, aegis_server=debug) info

See the User Guide and Security for vault, encryption and LDAP/OAuth settings.

Verify Installation

Check Server Status

curl http://localhost:9090/health | jq

Expected response:

{
  "status": "healthy",
  "version": "0.6.0"
}

Test Query

curl -X POST http://localhost:9090/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1 + 1 AS result"}'

Access Dashboard

Open http://localhost:8000 in your browser.

Default credentials: demo / demo

Using the CLI

# Install CLI (from crates.io)
cargo install aegisdb-cli

# Or install from source
cargo install --path crates/aegis-cli

# Check server status (port 9090)
aegis-client -s http://localhost:9090 status

# Run queries (subcommand comes AFTER the database flag)
aegis-client -s http://localhost:9090 query "CREATE TABLE users (id INT, name TEXT)"
aegis-client -s http://localhost:9090 query "INSERT INTO users VALUES (1, 'Alice')"
aegis-client -s http://localhost:9090 query "SELECT * FROM users"

# Interactive shell
aegis-client -s http://localhost:9090 shell

Using the Client SDK

Rust

use aegis_client::AegisClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AegisClient::connect("localhost:9090").await?;

    client.execute("CREATE TABLE users (id INT, name TEXT)").await?;
    client.execute("INSERT INTO users VALUES (1, 'Alice')").await?;

    let rows = client.query("SELECT * FROM users").await?;
    for row in rows {
        println!("{:?}", row);
    }

    Ok(())
}

Python

from aegis_client import AegisClient

client = AegisClient("localhost:9090")

client.execute("CREATE TABLE users (id INT, name TEXT)")
client.execute("INSERT INTO users VALUES (1, 'Alice')")

for row in client.query("SELECT * FROM users"):
    print(row)

JavaScript

import { AegisClient } from '@aegis-db/client';

const client = new AegisClient('localhost:9090');

await client.execute('CREATE TABLE users (id INT, name TEXT)');
await client.execute("INSERT INTO users VALUES (1, 'Alice')");

const rows = await client.query('SELECT * FROM users');
rows.forEach(row => console.log(row));

PM2 Deployment (Production)

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'aegis-server',
    script: './target/release/aegis-server',
    cwd: '/opt/Aegis-DB',
    env: {
      AEGIS_PORT: 9090,
      AEGIS_DATA_DIR: '/var/lib/aegis',
      RUST_LOG: 'info'
    }
  }]
};

Start with PM2:

pm2 start ecosystem.config.js
pm2 save
pm2 startup

Next Steps