Getting Started

This guide walks through installing the AEGIS binary, starting the required backing services, configuring the orchestrator, and executing a demo agent.

Prerequisites

Dependency	Minimum Version	Notes
Docker	24.0+	Required for agent container execution in development
Docker Compose	v2.20+	Used to start the local backing services stack
Linux	Kernel 5.15+	Required for Firecracker production mode (Docker mode works on macOS/WSL2)
PostgreSQL	15+	State persistence; started via Compose in local dev
SeaweedFS	Latest stable	Volume storage backend; started via Compose
Temporal	1.24+	Workflow durability; started via Compose

For local development, all backing services are provided via Docker Compose. You do not need to install PostgreSQL, SeaweedFS, or Temporal separately.

Install the AEGIS Binary

Download the latest release for your platform from the GitHub Releases page.

# Linux x86_64
curl -fsSL https://github.com/100monkeys-ai/aegis-orchestrator/releases/latest/download/aegis-linux-x86_64.tar.gz \
  | tar -xz -C /usr/local/bin

# Verify installation
aegis --version

The release archive contains a single aegis binary. Place it anywhere on your PATH.

Start the Local Stack

Clone the examples repository — it contains the Docker Compose stack and example agents:

git clone https://github.com/100monkeys-ai/aegis-examples.git
cd aegis-examples

Copy the environment file and start all backing services:

cp deploy/.env.example deploy/.env
docker compose -f deploy/docker-compose.yml up -d

This starts PostgreSQL, SeaweedFS, Temporal, Keycloak, Ollama, and the Cortex services. Wait ~30 seconds for Temporal to finish initializing:

docker compose -f deploy/docker-compose.yml ps

All services should show running (healthy).

Configure the Orchestrator

Copy the reference configuration and edit it for your environment:

cp deploy/aegis-config.yaml my-aegis-config.yaml

At minimum, set your LLM provider credentials. The example below uses OpenAI:

node:
  id: local-dev-node
  listen_addr: "0.0.0.0:8080"
  grpc_addr: "0.0.0.0:9090"
  log_level: info

runtime:
  type: docker
  image_pull_policy: always

llm:
  providers:
    - name: openai
      type: openai
      api_key: "env:OPENAI_API_KEY"
      model: gpt-4o
      max_tokens: 4096
  aliases:
    default: openai

storage:
  backend: seaweedfs
  master_addr: "localhost:9333"

database:
  url: "postgres://aegis:aegis@localhost:5432/aegis"

temporal:
  namespace: aegis-default
  host_port: "localhost:7233"

Export your API key:

export OPENAI_API_KEY="sk-..."

See Node Configuration Reference for a full annotated walkthrough of every configuration field.

Start the Daemon

aegis daemon --config my-aegis-config.yaml

The daemon starts the gRPC server, HTTP server, NFS storage gateway, and event bus. You should see output similar to:

2026-02-23T10:00:00Z  INFO aegis_core: AEGIS orchestrator starting
2026-02-23T10:00:00Z  INFO aegis_core: gRPC server listening on 0.0.0.0:9090
2026-02-23T10:00:00Z  INFO aegis_core: HTTP server listening on 0.0.0.0:8080
2026-02-23T10:00:00Z  INFO aegis_core::nfs: NFS server ready
2026-02-23T10:00:00Z  INFO aegis_core: Ready

Run the daemon in the background or manage it with systemd. See Docker Runtime for the systemd unit example.

Deploy a Demo Agent

The aegis-examples repo you cloned earlier includes agent manifests ready to deploy. Start with the hello-world agent:

# Deploy the hello-world agent
aegis agent deploy ./hello-world/agent.yaml

# Confirm it is deployed
aegis agent list

Example output:

ID                                    NAME         STATUS     RUNTIME
a1b2c3d4-0000-0000-0000-000000000001  hello-world  deployed   docker

Run Your First Execution

aegis execute \
  --agent hello-world \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
  --watch

The --watch flag streams iteration events to the terminal as they happen:

[Execution a1b2c3d4-1111-...] Started
[Iteration 1] Running...
[Iteration 1] Tool call: fs.write /workspace/solution.py
[Iteration 1] Tool call: cmd.run python /workspace/test_solution.py
[Iteration 1] Validation: score=0.92 confidence=0.88 → Success
[Execution a1b2c3d4-1111-...] Completed in 1 iteration (12.4s)

Retrieve the execution record:

aegis execution get a1b2c3d4-1111-...

What's Next

Writing Your First Agent — write a custom agent.yaml and bootstrap.py from scratch.
The Execution Loop — understand how the 100monkeys loop and inner tool interception work.
Agent Manifest Reference — every field in the manifest spec.
Deployment: Infrastructure Overview — moving to production.

Getting Started

On this page