Installation and deployment
The server is part of the agenticml-lite package (Python 3.10+, POSIX only). It needs version 3.0, which is a pre-release installed from GitHub until it is on PyPI.
Installation
Section titled “Installation”Create a dedicated virtual environment and install agenticml-lite:
sudo python3 -m venv /opt/agenticmlsudo /opt/agenticml/bin/python -m pip install agenticml-lite3.0 is not on PyPI yet, so this installs 1.0.0, which has no server. Until 3.0 is published, install it from GitHub instead (this follows the dev branch, so it moves as development continues):
sudo /opt/agenticml/bin/python -m pip install 'agenticml-lite @ git+https://github.com/agenticML/agenticml-lite@dev'Optional server extras
Section titled “Optional server extras”Install optional extras depending on your deployment backend:
# PostgreSQL database backendsudo /opt/agenticml/bin/pip install "agenticml-lite[postgres]"
# Amazon S3 object storagesudo /opt/agenticml/bin/pip install "agenticml-lite[s3]"
# Firebase ID token verificationsudo /opt/agenticml/bin/pip install "agenticml-lite[firebase]"
# Full hosted bundle (PostgreSQL, S3, Firebase)sudo /opt/agenticml/bin/pip install "agenticml-lite[hosted]"While 3.0 is only on GitHub, add the source to the extra, for example 'agenticml-lite[hosted] @ git+https://github.com/agenticML/agenticml-lite@dev'.
Running the server
Section titled “Running the server”Start the server using agenticml server serve:
/opt/agenticml/bin/agenticml server serve \ --data /var/lib/agenticml-server \ --host 127.0.0.1 \ --port 8080 \ --public-url https://aml.example.com--data DIR: server data directory. Defaults toAGENTICML_SERVER_DATA, then~/.agenticml-server.--database URL: SQL database URL. Defaults tosqlite:///<data>/server/agenticml.dbor PostgreSQL (postgresql://...).--objects URL: blob storage backend. Defaults tofile://(local disk) or Amazon S3 (s3://bucket/prefix).--host: interface to bind (defaults to127.0.0.1).--port: TCP port (defaults to8080).--public-url: canonical public HTTPS URL (AGENTICML_SERVER_PUBLIC_URL).
TLS proxy
Section titled “TLS proxy”The server serves plain HTTP over its configured port. In production or across a network, terminate TLS using a reverse proxy and configure the public URL:
Laptop or workstation (Tailscale)
Section titled “Laptop or workstation (Tailscale)”To share the server securely across your Tailscale network:
- Forward port 8080 to your Tailscale network:
Terminal window tailscale serve --bg 8080 - Set your Tailscale machine URL and start the server:
Or run
Terminal window export AGENTICML_SERVER_PUBLIC_URL=https://<machine>.<tailnet>.ts.net/opt/agenticml/bin/agenticml server serve --port 8080agenticml server upto automatically expose the server via Tailscale Funnel.
Production reverse proxy
Section titled “Production reverse proxy”Use Caddy, Nginx, or an AWS Application Load Balancer to terminate TLS and forward requests to 127.0.0.1:8080. Always configure --public-url (or AGENTICML_SERVER_PUBLIC_URL) to match the public HTTPS endpoint for Host and Origin validation.
Systemd service
Section titled “Systemd service”For production deployments on Linux, run the server as a systemd system service using the unit provided in deploy/systemd/agenticml-server.service:
- Install the package and create the dedicated service user:
The unit is fetched from
Terminal window sudo python3 -m venv /opt/agenticmlsudo /opt/agenticml/bin/python -m pip install agenticml-lite# 3.0 is not on PyPI yet; use the GitHub install shown under Installation insteadsudo useradd --system --home /var/lib/agenticml-server --shell /usr/sbin/nologin agenticmlsudo curl -fsSL -o /etc/systemd/system/agenticml-server.service https://raw.githubusercontent.com/agenticML/agenticml-lite/main/deploy/systemd/agenticml-server.servicemainbecause there is no 3.0 tag yet. Once 3.0.0 is released, use the tag that matches the agenticml-lite version you installed (pip show agenticml-lite). - Edit
AGENTICML_SERVER_PUBLIC_URLin the unit (orsudo systemctl edit agenticml-server), then reload systemd:Terminal window sudo systemctl daemon-reloadsudo systemctl enable --now agenticml-server - Check status and view logs:
Terminal window sudo systemctl status agenticml-serversudo journalctl -u agenticml-server -f
The unit’s StateDirectory=agenticml-server automatically manages /var/lib/agenticml-server owned by the agenticml user.
Configuration options
Section titled “Configuration options”agenticml server serve accepts the following options:
| Flag | Environment variable | Default | Description |
|---|---|---|---|
--data DIR |
AGENTICML_SERVER_DATA |
~/.agenticml-server |
Path to server data directory. |
--database URL |
AGENTICML_SERVER_DATABASE_URL |
sqlite:///<data>/server/agenticml.db |
Server database connection URL. |
--objects URL |
AGENTICML_SERVER_OBJECTS |
file:// |
Object store backend (file:// or s3://bucket/prefix). |
--host HOST |
127.0.0.1 |
Network interface to bind. | |
--port PORT |
8080 |
Port to listen on. | |
--public-url URL |
AGENTICML_SERVER_PUBLIC_URL |
unset | Canonical public URL (e.g. https://aml.example.com). |
--trusted-proxy CIDR |
AGENTICML_SERVER_TRUSTED_PROXIES |
unset | Trust proxy CIDR for X-Forwarded-For and identity headers. |
--identity-header PRESET |
AGENTICML_SERVER_IDENTITY_HEADER |
unset | Honour proxy identity header (alb, tailscale, oauth2-proxy). |
--firebase-project ID |
AGENTICML_SERVER_FIREBASE_PROJECT |
unset | Firebase project ID for token verification. |
--firebase-api-key KEY |
AGENTICML_SERVER_FIREBASE_API_KEY |
unset | Firebase web API key. |
--firebase-auth-domain HOST |
AGENTICML_SERVER_FIREBASE_AUTH_DOMAIN |
unset | Firebase auth domain. |
--limits FILE |
AGENTICML_SERVER_LIMITS |
unset | JSON file defining workspace usage limits. |
--open-signup |
AGENTICML_SERVER_OPEN_SIGNUP |
off | Allow verified Firebase sign-in to create an account and workspace. |
--admin-emails LIST |
AGENTICML_SERVER_ADMIN_EMAILS |
unset | Comma-separated emails granted server admin at their next verified Firebase sign-in. Ignored without Firebase. |
--min-client-version X.Y |
AGENTICML_SERVER_MIN_CLIENT_VERSION |
2.2 |
Reject agenticml-lite clients older than X.Y on /v2 requests with HTTP 426. |
Two more environment variables apply to S3 object storage:
AGENTICML_SERVER_S3_ENDPOINT_URL: custom S3 endpoint, for MinIO, LocalStack or a VPC endpoint.AGENTICML_SERVER_S3_KMS_KEY_ID: AWS KMS key ID or ARN. Uploads then useaws:kmsencryption instead ofAES256.
Continue to Authentication and keys to configure access and workspaces.