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

100monkeys.ai published a getting-started guide for AEGIS, its beta self-hosted orchestrator that runs autonomous agents in isolated, policy-enforced runtimes with durable state. The guide walks through installing the CLI on a fresh Ubuntu VPS via a curl-piped install script, running `aegis init` to bring up a Docker Compose stack, executing a hello-world agent task, and defining a workflow with a `kind: Human` approval gate that pauses an agent until a person approves. The company cautions that the quick install uses an in-memory secrets store with no Keycloak IAM or TLS and is intended for local testing only, directing production users to its aegis-deploy repository.

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 https://docs.100monkeys.ai/docs/getting-started 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 https://github.com/100monkeys-ai/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 https://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 https://github.com/100monkeys-ai/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 https://100monkeys.ai/blog/approval-step-for-an-agent-orchestrator . For what to record around each run, read A traceability checklist for AI agents in production https://100monkeys.ai/blog/ai-agent-traceability-checklist . 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 https://carbonforge.dev/guides/claude-code-mcp . Install AEGIS from 100monkeys.ai https://100monkeys.ai/?utm source=devto&utm medium=article&utm campaign=push-2026-10-28 Originally published at https://100monkeys.ai/blog/install-aegis-on-ubuntu-vps https://100monkeys.ai/blog/install-aegis-on-ubuntu-vps