100monkeys.ai

Blog · Guide · 28 October 2026

Install AEGIS on a fresh Ubuntu VPS and run your first approved task

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.

Before you start

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:

Step 1. Run the installer

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.

Step 2. Check the binary and the stack

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.

Step 3. Run the guided setup and choose a model provider

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.

Step 4. Run hello-world once, unattended

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.

Step 5. Write a workflow with an approval gate

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: []

Step 6. Deploy it and start a run

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.

Step 7. Read the draft, then answer

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.

What this does not cover

Next

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