Installing Agent Access Manager¶
This page covers the standalone install: everything on one machine, which is how most deployments start and where every evaluation should. For multi-machine and Kubernetes, see How it is deployed.
Before you start¶
You need three things:
- Docker Engine with the Compose v2 plugin. Docker Desktop on Windows and macOS includes it. On Linux,
docker compose versionshould print v2 or later. - About 4 GB of free memory. More if you enable the SIEM tier, which adds OpenSearch.
- A hostname your users can reach. This one matters more than it looks - see below.
Why localhost will not do¶
Agent Access Manager runs in containers. Inside a container, localhost means that container, not your machine. A public URL of http://localhost:8080 would make the browser session, the SSO redirects, and the dashboard's own API calls point at the wrong place, so the installer rejects it outright.
Use the machine's hostname (the default), a DNS name, or its IP address. The installer checks that the name actually resolves before accepting it.
The same trap catches locally hosted models - see A local model is refused under Troubleshooting.
Install in one command¶
Linux and macOS
Windows (PowerShell)
That is the whole installation. It asks nothing on the happy path.
What it does¶
- Checks Docker is present and running, and tells you how to fix it if not.
- Reads the published version pointer to find the current release.
- Downloads the deploy kit and verifies its SHA-256 checksum before unpacking. A failed checksum aborts the install.
- Unpacks to
~/.aimanager(Linux and macOS) or%LOCALAPPDATA%\AIManager(Windows). - Picks a public URL:
http://<this-machine-hostname>:8080, used only once the name is confirmed to resolve. - Generates every secret - the admin password, the database password, the SSO admin, and the catalog master key - into
deploy/.env. - Pulls the container image and starts the stack.
- Waits until the app is actually serving, printing progress. First boot migrates the database and imports the SSO realm, which takes a few minutes.
- Creates a desktop launcher, then prints the dashboard URL and your first-login credentials.
Because of step 8, when it hands you a URL the dashboard is ready. If you open it earlier you may briefly see a "starting" page, which refreshes itself.
Running it again upgrades in place¶
Re-run the same command to move to the current release. Your deploy/.env and all data volumes are kept, so secrets and history survive.
Options¶
A piped script cannot take parameters directly, so pass them through the pipe:
& ([scriptblock]::Create((irm https://agentaccessmanager.com/get.ps1))) -Url https://gateway.acme.com
| Option | Windows form | What it does |
|---|---|---|
--url URL |
-Url |
The address users reach the dashboard at. Sets the port too if the URL carries one. |
--port N |
-Port |
Listen on a different port. Default 8080. |
--version vX.Y.Z |
-Version |
Install a specific release instead of the latest. |
--image TAG |
-Image |
Use a specific image, for example one loaded from an air-gapped bundle. |
--license FILE |
-License |
Apply a license token during installation. |
--dir PATH |
-Dir |
Install somewhere other than the default directory. |
--channel NAME |
-Channel |
Install from a channel such as preview rather than the latest release. |
--no-open |
-NoOpen |
Do not open a browser at the end. |
Serving over HTTPS at a real name is a reverse-proxy concern: terminate TLS in front and pass an https:// URL, and the installer marks its session cookies secure to match.
First run¶
Open the dashboard and sign in with the credentials the installer printed. The setup wizard then walks you through four steps:
- Create an organization - the tenant that owns keys, budgets, and policy.
- Connect a provider - OpenAI, Anthropic, Gemini, or a local model server. Presets fill in the base URL for you.
- Issue a virtual key - what your applications will authenticate with. Your vendor's own key never leaves the gateway.
- Send a test message - in a chat panel on the page, so you can confirm the whole path works before wiring anything up.
You will be asked to change the initial SSO password on first sign-in.
Pointing an application at it¶
Your gateway speaks the OpenAI API, so most clients need only a base URL and a key:
curl http://<your-host>:8080/v1/chat/completions -H "Authorization: Bearer <your-virtual-key>" -H "Content-Type: application/json" -d '{"model":"<your-alias>","messages":[{"role":"user","content":"hello"}]}'
The same base URL also serves /v1/messages (Anthropic), /v1/responses, /v1/embeddings, and GET /v1/models.
Day-to-day operation¶
Run these from your install directory. On Windows use .\aimanager.ps1 with the same subcommands.
stop and start are there too, and a desktop launcher does the same thing if you prefer clicking.
Backups¶
This takes a consistent copy of every data volume plus deploy/.env. Keep them together: a backup cannot be restored without its .env, because the catalog master key in that file is what decrypts your stored provider credentials.
Restoring replaces current data, so it will ask for confirmation.
The master key must not change
AIM_CATALOG_MASTER_KEY in deploy/.env encrypts your provider API keys at rest. If you lose it or change it, those stored credentials cannot be decrypted and must be re-entered. Back that file up somewhere safe, and treat it as a secret.
Applying a license¶
The free CORE tier needs no license.
It takes effect immediately, with no restart. If the license unlocks features needing extra infrastructure - OpenSearch for the SIEM tier - bring it up with:
Starting over without reinstalling¶
Wipes the application's data and returns you to the setup wizard, keeping your secrets and SSO users. Useful after an evaluation.
Uninstalling¶
Removes the containers and the data volumes, removes the desktop launcher, then asks whether to delete the install directory as well. That last part is a separate question because the directory holds deploy/.env and therefore your master key.
To skip the question in a script, add --purge to delete the directory too, or --yes on its own to keep it.
Air-gapped installation¶
When a release has images-*.tar.zst bundles attached, load them on the target machine first and the installer will not need registry access.
The second is only needed for the SIEM tier. You can also produce a bundle from a machine that does have access:
Then, on the air-gapped machine:
Installing from the release kit by hand¶
If you would rather not pipe a script, download the kit from the release page and run the installer yourself.
Add --yes to accept every default without prompting, which is what you want in a provisioning script.
Trying an unreleased build¶
Preview builds exist to test a change before it ships. They are not supported, and the user guide is omitted from preview images, so /guide will not be there.
A preview uses the same default directory and port as a real install, so it will take over an existing one on that machine. Pass --dir and --port to keep them apart.
Troubleshooting¶
A local model is refused¶
You register Ollama, vLLM, or LM Studio and every call fails with a connection refused.
The gateway runs in a container, so localhost there is the container itself, not your machine. Register a host-local model server as:
On Linux, also make the model server listen beyond loopback - for Ollama, set OLLAMA_HOST=0.0.0.0. Docker Desktop needs no such change.
The dashboard warns you about this as you type a localhost address, and offers to correct it.
The dashboard shows a "starting" page¶
That page is served while the application boots, and it refreshes itself. First boot runs database migrations and imports the SSO realm, so a few minutes is normal. If it lasts longer, check ./aimanager.sh logs.
Nothing resolves at the URL¶
The hostname has to resolve from the machines that will use it, not only from the server. Re-run the installer with --url pointing at a name your users can reach, or use the host's IP address.
Sign-in redirects to the wrong address¶
SSO redirect URIs are pinned to the public URL chosen at install time. If the address changed, re-run the installer with the correct --url to re-render the realm.
The installer says it is installing from somewhere unexpected¶
If it reports installing from AIM_SITE=..., an environment variable is redirecting it - most often left over from installing a preview in the same terminal. Clear it and try again: