Getting Started
Install AEGIS, start the local stack, and run your first agent execution.
aegis init is designed for local testing and evaluation only. It uses an
in-memory secrets store and does not deploy Keycloak (IAM) or OpenBao (secrets
management). For production deployments, use the aegis-deploy
repository.
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 | bashhttps://get.100monkeys.ai redirects to install.sh on the main branch of aegis-orchestrator. The installer runs on Ubuntu or Debian (it needs apt-get) and on macOS, and does this:
- Version. It installs
1.0.1-beta. SetAEGIS_VERSIONto install another release tag, orlatestfor the newest GitHub release. When the newest release cannot be read from GitHub, because the lookup fails or its answer is not release JSON, the installer prints "Could not resolve latest GitHub release; falling back to pinned version 1.0.1-beta" and installs1.0.1-beta. - System packages. On Linux it installs
curl,ca-certificatesandfuse3where they are missing. - libfuse3. The
aegisbinary linkslibfuse3.so.3. On x86_64 Linux without it, the installer installslibfuse3-3; on a release that has no such package, such as Ubuntu 25.10 and later, which shiplibfuse3-4, it installs Ubuntu'slibfuse3-33.14.0-5build1 package, checked against its pinned SHA-256. - Docker. On macOS, when Docker Desktop is installed but not running, the installer stops with "Docker Desktop is installed but not running. Start Docker Desktop, wait until it is ready, and rerun this installer." On Linux, when Docker is installed and its daemon is not reachable, the installer starts the engine (with
systemctl, elseservice; in WSL it retries once withiptables-legacywhen the engine failed on nftables). When the engine does not start, it prints the engine's log and stops. When the engine runs but your user cannot reach it, it adds you to thedockergroup and uses it for the rest of the install throughsg; when you still cannot reach it, it prints the client's error, the socket's permissions and your groups, and stops. Without Docker, on Ubuntu or Debian (WSL included, with no Docker Desktop) it installs Docker Engine (docker-ce); on macOS it stops and asks you to install Docker Desktop. - The CLI. It downloads the release's archive, installs
aegisto/usr/local/bin/aegis, and starts the stack withaegis up --tag <version>, where<version>is the release it installed, never the wordlatest.
The 1.0.1-beta release carries the Linux x86_64 archive, aegis-linux-x86_64.tar.gz, and its .sha256. Every published package and image is listed on Releases.
Verify the installation:
aegis --versionAuthenticate
Before running any commands against a remote AEGIS environment, authenticate:
aegis auth loginThis uses dev.100monkeys.ai by default. To target a different environment:
aegis auth login --env prod.100monkeys.aiThe 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 initaegis 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 validateSee 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."}' \
--followIf 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: Agentmanifest 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.
Running tools on your own hosts
If you've finished the local-stack tour and want AEGIS to execute MCP tool calls on a host you own — your laptop, home server, work VM — install the AEGIS edge daemon. The daemon binds to your tenant via a one-time enrollment token, then opens an outbound gRPC stream to the platform so it works behind NAT.
- Edge Mode Overview — start here for the conceptual model.
- Edge Host Setup — the step-by-step install + enroll guide for the Zaru SaaS flow.