Deployment guide

1. Install

Windows sidecar

Unzip the public archive.
Double-click AEGIS Suite.bat. That puts an AEGIS Suite icon on the desktop and in the Start menu, starts Docker, and opens Command Deck.
Sign up in the popup, or paste a key if you were issued one. You are audit-only until a paid key is active. Do not click Sign up if you already have an AEGIS-1 or AEGIS-ENV key — that creates an audit-only account and ignores the key.
Classic scripts still work: start.bat, attach.bat, stop.bat.

macOS / Linux sidecar

Unzip, then run ./start.sh (Docker must be running).
Sign up at http://localhost:3000.
Protect an agent in Command Deck, or ./attach.sh my-bot -- python your_agent.py

Aegis Node (Ubuntu 24.04)

Copy the same unzipped folder onto Ubuntu 24.04 (Multipass, a cloud image, or an existing VM — not Docker Desktop WSL). Aegis does not ship a Linux distro.
Run ./start-node.sh or ./appliance/multipass-launch.sh.
Stock 24.04 has no bpf LSM. start-node.sh writes GRUB and may reboot.
After reboot, optional EPERM film (uses shipped prebuilts, no crates.io): sudo bash scripts/prove_kernel_grant.sh

2. First boot

Open http://localhost:3000. First boot is a sign-up / log-in popup. Anyone can create an account. You are audit-only until you upgrade.
Gold audit-only banner after activation. Kernel chip: Userspace on Docker Desktop; Audit LSM on Aegis Node until a paid key.
Default policy default-allowlist includes tools search, calculator, read_file, http_request, shell_exec (HITL hold).
Sequence rules such as read_file → http_request (exfil chain). Intent bindings: read_file limited to /data, /workspace, /tmp/aegis-work.
Every paid key (Builder, Standard, Enterprise) licenses 403s and kernel EPERM; they differ by node cap. Kernel EPERM still needs Aegis Node on Ubuntu 24.04. Docker Desktop stays userspace.
First boot pulls the proxy and Command Deck from GHCR, then builds the control plane from the zip (Python/pip, about 1–2 minutes). It does not compile Rust.

3. Attach

In Command Deck open Protect. Type an agent name, choose the script or binary, click Protect. That writes the same session env attach.bat used to print, and wraps the process so you do not edit SDK code.
CLI: attach.bat support-bot -- python your_agent.py or ./attach.sh support-bot -- python your_agent.py
That health-checks http://127.0.0.1:8080/health, writes .aegis-agent.env, and prints base URLs for OpenAI, Claude, Gemini, Azure, Groq, Grok, Mistral, and other OpenAI-compatible vendors.
Python wrap injects session + process TGID via examples/aegis_pth for the OpenAI, Azure, Anthropic, Gemini, and Groq SDKs.
From another machine: AEGIS_PROXY_BASE=http://<node-ip>:8080 ./attach.sh support-bot
GET http://127.0.0.1:8080/health must return {"status":"ok"}.

Windows:     attach.bat support-bot -- python your_agent.py
macOS/Linux: ./attach.sh support-bot -- python your_agent.py

4. Verify an enforced 403

Wait for the Command Deck audit banner before python test_proxy.py. Default Free Audit Mode returns 200 with X-Aegis-Decision: WOULD_BLOCK instead of 403. After any paid or trial AEGIS-1 key, the same cases return 403.

Call	Audit mode (default)	After a paid or trial key
calculator	Allowed (the allow is what matters)	Same
delete_database	200 + WOULD_BLOCK (not on the allowlist)	403 Aegis Guardrail
read_file /etc/passwd	200 + WOULD_BLOCK intent	403 intent (path outside /data)
shell_exec	200 + WOULD_BLOCK HITL	403 HITL (layer=hitl)
Ignore all previous instructions…	200 + WOULD_BLOCK signature	403 signature
read_file /data/report.pdf then http_request	200 + WOULD_BLOCK sequence	403 sequence if both use session exfil

test_proxy.py POSTs OpenAI-style tool_calls to http://127.0.0.1:8080/v1/chat/completions and exits non-zero if a deny is not observed (403, or any origin status with X-Aegis-Decision: WOULD_BLOCK in audit mode). Fail-closed CI uses python evals/run_bench.py --require-403 — audit-mode WOULD_BLOCK that still forwards is a failure.

5. Safe Docker defaults

The base Compose stack runs userspace protection with eBPF disabled, no host Docker socket, no added data-plane capabilities, and no writable kernel mounts.
UI and proxy ports bind to localhost.
Container management agent tools require a separately reviewed Docker integration.
The base stack does not provide kernel EPERM enforcement. Do not interpret userspace results as kernel proof.
Live model traffic stays on the configured deployment path. Customers retain their vendor API keys. Phone-home behavior is not required for enforcement.
Production deployments should enable fail-closed settings and protect Redis, the control-plane API, and the proxy on a private network.

6. Privileged / appliance caveats

The appliance compose overlay (appliance/docker-compose.appliance.yml) is privileged: true with host PID and read-write /sys/kernel/debug plus /sys/kernel/tracing. That is host control from inside the container. Use it on a dedicated Aegis Node VM, not on a shared production host.
For kernel enforcement, use a dedicated Aegis Node VM and the documented appliance overlay with the contract overlay.
In Docker sidecar (AEGIS_EBPF=0), Aegis is a proxy. It only sees traffic sent to it: env base-URL variables, or a wrapped Python process whose SDK constructors are patched.
A call made with raw urllib, requests, httpx, curl, a subprocess, or any compiled binary that ignores those env vars goes straight to the vendor and is never evaluated. That is a property of proxy interception, not a policy failure.
Covering a process regardless of language or HTTP client requires the kernel path: the BPF LSM on an Aegis Node, where a divergence is -EPERM at the syscall rather than a 403 on a hop.
Never claim that an agent is protected if it can bypass the proxy.
Packaged installs do not pull GitHub threat lists. The zip ships a signed intel/drop pack. Unsigned JSON is rejected unless AEGIS_INTEL_ALLOW_UNSIGNED=1 (do not do that in production).
Do not commit or forward the AEGIS-1 key. Use the recover URL.

Install, attach, and verify an enforced 403