Getting Started

AEGIS manages the full lifecycle of AI agents — from manifest deployment through iterative execution, secure tool access, workflow coordination, and multi-agent swarms. Agents run in isolated containers, tools are proxied through a signed security layer, and every execution is observed, scored, and learned from.

This guide walks you through installing AEGIS, starting the local stack, and running your first agent execution.

Install AEGIS CLI

curl -fsSL https://get.100monkeys.ai | bash

Verify the installation:

aegis --version

Authenticate

Before running any commands against a remote AEGIS environment, authenticate:

aegis auth login

This uses dev.100monkeys.ai by default. To target a different environment:

aegis auth login --env prod.100monkeys.ai

The CLI will display a one-time code and URL. Open the URL in your browser, enter the code, and the CLI will confirm when authentication is complete.

For CI/CD pipelines, use an API key instead — see Authentication.

Initialize the Local Stack

Run the guided setup:

aegis init

aegis init configures the local stack, writes config files, starts services, and can optionally deploy the hello-world example agent as a smoke test.

Alternative: Deploy with aegis-deploy

For a full platform deployment with all services (database, Temporal, observability, etc.):

git clone https://github.com/100monkeys-ai/aegis-deploy.git
cd aegis-deploy
cp .env.example .env
# Edit .env with your credentials

make setup
make registry-login
make deploy PROFILE=development
make validate

See Podman Deployment for full details on profiles and Makefile targets.

Deploy and Run the hello-world Agent

If you accepted the smoke-test prompt during aegis init, execute it with:

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

If you skipped example deployment in aegis init, run aegis init again and enable the hello-world smoke test.

The --follow flag streams iteration events to the terminal as they happen. You'll see output similar to:

2026-02-25T13:56:43.091943Z  INFO Delegating to daemon API
Executing agent 88b73d1b-0da0-4b92-9376-fd744b9cafbf...
✓ Execution started: f668f593-370f-4c19-b043-0487e9bd1ae5
[2026-02-25T13:56:43.140898+00:00] Execution started
[2026-02-25T13:56:43.164238272+00:00] Iteration 1
[2026-02-25T13:57:34.455428513+00:00] LLM [default]
[STDOUT] "First, I would write the required `fib_sequence` function in `/workspace/solution.py`:

The agent will generate code, run validation, and either succeed or refine across multiple iterations until it produces a working solution.

Going to Production?

aegis init is not suitable for production use. When you're ready to deploy for real users, use aegis-deploy — the official production deployment repository that includes Keycloak IAM, OpenBao secrets management, TLS via Caddy, and full observability.

See the Production Deployment Guide for full details.

What's Next

• Writing Your First Agent — create a declarative kind: Agent manifest and run it.
• Custom Runtime Agents (Advanced) — only if you need a custom container or bootstrap.py.
• Building Workflows — compose multi-step agent flows with declarative workflow FSMs.
• 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.