This repository provides the complete infrastructure for running GenAI agents, including:
- Backend
- Router
- Master Agents
- PostgreSQL Database
- Frontend
- CLI
- Redis
- Celery
The system supports multiple kinds of Agents:
| Agent Type | Description |
|---|---|
| GenAI Agents | Connected via genai-protocol library interface. |
| MCP Servers | MCP (Model Context Protocol) servers can be added by pasting their URL in the UI. |
| A2A Servers | A2A (Agent to Agent Protocol) servers can be added by pasting their URL in the UI. |
Make sure you have the following installed:
-
make(optional)- macOS:
brew install make - Linux:
sudo apt-get install make
- macOS:
-
Clone the repository:
git clone https://github.com/genai-works-org/genai-agentos.git cd genai-agentos/ -
Create a
.envfile by copying the example (can be empty and customized later):cp .env-example .env
- A
.envfile should be present for configuration. - All variables in
.env-exampleare commented. You can customize any environment setting by uncommenting the relevant line and providing a new value.
- A
-
Start Docker desktop and ensure it is running.
-
Start the infrastructure:
make up # or alternatively docker compose up -
After startup:
- Frontend UI: http://localhost:3000/
- Swagger API Docs: http://localhost:8000/docs#/
- OpenAI: gpt-4o
Ngrok can be used to expose the local WebSocket endpoint.
-
Install Ngrok:
- macOS (Homebrew):
brew install ngrok/ngrok/ngrok - Linux:
sudo snap install ngrok
- macOS (Homebrew):
-
Authenticate Ngrok:
-
Sign up or log in at ngrok dashboard.
-
Go to the "Your Authtoken" section and copy the token.
-
Run the command:
ngrok config add-authtoken <YOUR_AUTH_TOKEN>
-
-
Start a tunnel to local port 8080:
ngrok http 8080
-
Copy the generated WebSocket URL and update the
ws_urlfield in:genai_session.session.GenAISession
🤖GenAI Agent registration quick start (For more data check CLI)
cd cli/
python cli.py signup -u <username> # Register a new user, also available in [UI](http://localhost:3000/)
python cli.py login -u <username> -p <password> # Login to the system, get JWT user token
python cli.py register_agent --name <agent_name> --description <agent_description>
cd agents/
# Run the agent
uv run python <agent_name>.py # or alternatively
python <agent_name>.py | Variable | Description | Example / Default |
|---|---|---|
FRONTEND_PORT |
Port to start a frontend | 3000 - default. Can be changed by run in terminal source FRONTEND_PORT=<your_port> |
ROUTER_WS_URL |
WebSocket URL for the router container |
ws://genai-router:8080/ws - host is either localhost or router container name |
SECRET_KEY |
Secret key for cryptographic operations - JWT/ LLM config encryption | $(openssl rand -hex 32) |
POSTGRES_HOST |
PostgreSQL Host | genai-postgres |
POSTGRES_USER |
PostgreSQL Username | postgres |
POSTGRES_PASSWORD |
PostgreSQL Password | postgres |
POSTGRES_DB |
PostgreSQL Database Name | postgres |
POSTGRES_PORT |
PostgreSQL Port | 5432 |
DEBUG |
Enable/disable debug mode - Server/ ORM logging | True / False |
MASTER_AGENT_API_KEY |
API key for the Master Agent - internal identifier | e1adc3d8-fca1-40b2-b90a-7b48290f2d6a::master_server_ml |
MASTER_BE_API_KEY |
API key for the Master Backend - internal identifier | 7a3fd399-3e48-46a0-ab7c-0eaf38020283::master_server_be |
BACKEND_CORS_ORIGINS |
Allowed CORS origins for the backend |
["*"], ["http://localhost"] |
DEFAULT_FILES_FOLDER_NAME |
Default folder for file storage - Docker file volume path | /files |
CLI_BACKEND_ORIGIN_URL |
backend URL for CLI access |
http://localhost:8000 |
✅ If your MCP server or A2A card is hosted on your local machine, make sure to change the host name from http://localhost:<your_port> to http://host.docker.internal:<your_port> and try again.
✅ Make sure your MCP server supports streamable-http protocol and is remotely accessible.Also make sure that you're specifiying full URL of your server, like - http://host.docker.internal:8000/mcp
sse protocol is officially deprecated by MCP protocol devs, stdio protocol is not supported yet, but stay tuned for future announcements!