Skip to main content

​
System Requirements

  • Python 3.12+
  • uv package manager (Install uv)
  • Node.js (optional, for Node.js-based MCP servers)

​
Step-by-Step Installation

​
1. Clone the Repository

git clone https://github.com/BenItBuhner/Agent-Chassis.git
cd agent-chassis

​
2. Install Dependencies

uv sync
This installs all Python dependencies including:
  • FastAPI and Uvicorn (web framework)
  • OpenAI SDK (LLM integration)
  • MCP (Model Context Protocol) libraries
  • Optional: Redis, SQLAlchemy, JWT libraries

​
3. Configure Environment

Create a .env file from the template: 
cp .env.example .env
Edit .env with your configuration. See Environment Variables for details. Minimum required configuration: 
OPENAI_API_KEY=sk-...
OPENAI_MODEL=kimi-k2-thinking

​
4. Configure MCP Servers (Optional)

Edit mcp_config.json to add MCP servers: 
{
  "mcpServers": {
    "Context7": {
      "url": "https://mcp.context7.com/mcp",
      "transport": "streamable-http"
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}
See MCP Servers Configuration for more details.

​
5. Run the Server

Development mode (with auto-reload): 
uv run uvicorn app.main:app --reload
Production mode: 
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000
Visit http://localhost:8000/docs for interactive API documentation.

​
Docker Installation

​
Using Docker Compose

docker-compose up --build

​
Using Dockerfile

docker build -t agent-chassis .
docker run -p 8000:8000 --env-file .env agent-chassis

​
Verification

​
Health Check

Check the health endpoint: 
curl http://localhost:8000/health
Expected response: 
{
  "status": "healthy",
  "persistence_enabled": false,
  "user_auth_enabled": false,
  "redis_connected": false,
  "database_connected": false
}

​
Test Agent Endpoint

curl -X POST http://localhost:8000/api/v1/agent/completion \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "model": "kimi-k2-thinking"
  }'

​
Optional: Enable Persistence

If you want server-side session persistence:
  1. Set up Redis: 
    REDIS_URL=redis://localhost:6379/0
  2. Set up PostgreSQL: 
    DATABASE_URL=postgresql+asyncpg://user:pass@localhost/agent_chassis
  3. Enable persistence: 
    ENABLE_PERSISTENCE=true
See Persistence Guide for detailed setup.

​
Optional: Enable User Authentication

If you want JWT-based user authentication:
  1. Set JWT secret: 
    JWT_SECRET_KEY=your-secure-secret-key-min-32-chars
  2. Configure Google OAuth (optional): 
    GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
  3. Configure email service: 
    SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]
  4. Enable user auth: 
    ENABLE_USER_AUTH=true
See Authentication Guide for detailed setup.

​
Troubleshooting

​
Port Already in Use

If port 8000 is already in use: 
uv run uvicorn app.main:app --port 8001

​
OpenAI API Key Not Found

Make sure your .env file contains: 
OPENAI_API_KEY=sk-...

​
MCP Server Connection Issues

Check your mcp_config.json syntax and ensure MCP servers are accessible. See MCP Servers Configuration for troubleshooting.

​
Database Connection Issues

If using persistence, verify:
  • Redis is running: redis-cli ping (should return PONG)
  • PostgreSQL is accessible: psql -h localhost -U user -d agent_chassis

​
Next Steps