Disclosure: 100monkeys.ai builds AEGIS, so read this guide as a maker's account. It was drafted by one of our AI agents from the public AEGIS documentation at docs.100monkeys.ai and reviewed by the company. Every command below is copied from those docs or from our home page. We did not run this exact sequence on a fresh VPS for this guide, and where the docs disagree with each other we say so instead of guessing.
AEGIS by 100monkeys.ai, in beta, is a self-hosted orchestrator that runs autonomous agents in isolated, policy-enforced runtimes with durable state. This guide takes a fresh Ubuntu server to a running local stack, then runs one agent behind a human approval gate, so the agent's work stops and waits until you answer yes.
Know what the quick install is for. The Getting Started page says it plainly: 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)." The Infrastructure Requirements page lists its IAM as "None (unauthenticated)" and its TLS as "None". For production the docs point to the aegis-deploy repository instead.
So on a VPS, treat this stack as a private lab. The CLI's health checks default to host 127.0.0.1 and port 8088. Do not open that port to the internet; reach the box over SSH.
You need:
sudo. The installer "runs on Ubuntu or Debian (it needs apt-get)". aegis-linux-x86_64.tar.gz.
Copy the line from 100monkeys.ai, where it is printed, and run it as your normal user:
curl -fsSL https://get.100monkeys.ai | bash
Read the script first if you prefer. The docs say https://get.100monkeys.ai redirects to install.sh on the main branch of aegis-orchestrator. On Linux it installs curl, ca-certificates and fuse3 where missing, installs libfuse3 where the binary needs it, and installs Docker Engine (docker-ce) when Docker is absent. When Docker runs but your user cannot reach it, it adds you to the docker group. It then installs aegis to /usr/local/bin/aegis and starts the stack with aegis up --tag <version>.
To pin a release, set AEGIS_VERSION to a release tag before running it; the docs list every published package on the Releases page.
aegis --version
aegis status
aegis status reports local stack health. If you were added to the docker group during the install, log out and back in so new shells carry the group.
aegis init
The wizard "prepares stack files, configures the node, starts Docker Compose services, verifies health, and can optionally load smoke-test agents". Accept the hello-world smoke test when it asks; the next step uses it. The configuration it writes maps the model aliases default, smart, judge and tool-judge on the provider you choose. The hello-world agent names smart, and an alias the node does not map fails with Model alias '<alias>' not found, so finish the provider prompt. Stack files go to ~/.aegis unless you pass --dir.
Prove the loop works before you add a gate:
aegis task execute hello-world \
--input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
--follow
--follow streams iteration events. The agent generates code, runs validation, and either succeeds or refines across iterations until its validators pass.
An approval in AEGIS is a workflow state of kind: Human. Save this as approved-task.yaml. It follows the shape of the example on the Building Workflows page, cut down to one agent and one gate:
apiVersion: 100monkeys.ai/v1
kind: Workflow
metadata:
name: approved-task
version: "1.0.0"
description: "One agent drafts, a person approves, then the run completes."
spec:
initial_state: DRAFT
states:
DRAFT:
kind: Agent
agent: hello-world
timeout: 600s
transitions:
- condition: on_success
target: APPROVE
- condition: on_failure
target: FAILED
APPROVE:
kind: Human
prompt: |
Draft:
{{DRAFT.output}}
Approve? (yes/no)
timeout: 86400s
transitions:
- condition: input_equals_yes
target: DONE
- condition: input_equals_no
target: FAILED
DONE:
kind: System
command: "echo 'Approved'"
transitions: []
FAILED:
kind: System
command: "echo 'Rejected or failed'"
transitions: []
aegis workflow deploy ./approved-task.yaml --force
aegis workflow run approved-task \
--input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}'
The run command prints an execution id. Watch it:
aegis workflow logs <execution-id> --follow --verbose
aegis workflow executions get <execution-id>
When the draft is done, executions get shows the current state as APPROVE (WAITING FOR HUMAN SIGNAL). Nothing after the gate runs until someone answers.
aegis workflow signal <execution-id> --response yes
Answer no to send the run to FAILED instead. A gate that nobody answers expires after its timeout; with the default behaviour the run is marked failed with the reason human_input_timeout.
One thing to know: the docs do not agree on the word. The Human Approvals page says a yes-or-no gate takes the responses ["yes", "no"]; the Building Workflows page signals --response approved; the CLI page shows --response "approve". We use yes because it is what the input_equals_yes transition is named for. If the run does not move, check executions get and try the other forms.
aegis init stack, anyone who reaches port 8088 can act on it.
For the reasoning behind the gate, read How to give an orchestrator an approval step. For what to record around each run, read A traceability checklist for AI agents in production. If you want your agents' notes and code in one record they can read and write over MCP, see Connect Claude Code to Carbon Forge over MCP.
Install AEGIS from 100monkeys.ai
Originally published at https://100monkeys.ai/blog/install-aegis-on-ubuntu-vps