Your personal AI assistant. Just chat with it to search for information, process files, write code, or draft reports. It automatically breaks down complex tasks and executes them step by step, showing you the results in real time.

• Deep Agent — multi-step reasoning with tool use, subagents, file I/O, and persistent memory
• Streaming chat — real-time SSE streaming with Markdown rendering and syntax highlighting
• Sandbox execution — isolated code execution via OpenSandbox, with automatic pip setup
• Tool call visualization — expandable tool call cards show args and results inline, in chronological order
• Skill system — dynamic skill installation from URLs, auto-restored on sandbox rebuild
• JWT authentication — user registration/login with thread-level isolation
• Persistent storage — Redis for thread metadata, MongoDB for conversation history and long-term memory
• Docker-first — multi-stage build bundles frontend and backend into a single image

┌──────────────────────┐     SSE + REST       ┌──────────────────────────┐
│  React frontend (Vite) │ ◄─────────────────► │   FastAPI server          │
│  Port 5173 (dev only)  │                     │   Port 8000              │
└──────────────────────┘                       └────────┬─────────────────┘
                                                        │
                              ┌─────────────────────────┼─────────────────────┐
                              │                         │                     │
                         ┌────▼────┐             ┌──────▼──────┐       ┌─────▼──────┐
                         │  Redis   │             │   MongoDB    │       │ OpenSandbox │
                         │ metadata │             │ checkpoints  │       │ code exec   │
                         │ sandbox  │             │ store/memory │       │ sandbox     │
                         └─────────┘             └─────────────┘       └────────────┘

• Python 3.11+ with uv or pip
• Redis (any version)
• MongoDB 7+
• OpenSandbox server
• Node.js 22+ (frontend development only)

cp .env.example .env
# Edit .env with your API keys and connection strings

Backend:

uv sync
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Frontend (in a separate terminal):

cd client
npm install
npm run dev       # → http://localhost:5173

The Vite dev server proxies /api requests to localhost:8000, so you get hot module replacement for the frontend while the backend handles API calls.

All endpoints are prefixed with /api. Protected endpoints require Authorization: Bearer <token>.

The streaming endpoint emits the following events:

The agent comes with a set of built-in tools accessible from the sandbox:

Additional tools can be integrated via MCP (Model Context Protocol).

├── src/
│   ├── main.py                              # FastAPI app entry point
│   ├── model_provider.py                    # LLM configuration
│   ├── api/
│   │   └── chat.py                          # Thread, run, and state endpoints
│   ├── auth/
│   │   ├── router.py                        # Registration and login endpoints
│   │   ├── security.py                      # JWT encode / decode
│   │   ├── models.py                        # User data models
│   │   └── dependencies.py                  # get_current_user dependency
│   ├── deep_agent/
│   │   ├── graph.py                         # Agent factory, caching, persistence
│   │   ├── opensandbox_backend.py           # OpenSandbox backend (create, reconnect, cleanup)
│   │   └── sub_agents.py                    # Subagent definitions
│   ├── tools/
│   │   ├── file_tool.py                     # File read/write/convert tools
│   │   ├── install_skill.py                 # Dynamic skill installation
│   │   ├── search_tool.py                   # Web search tool
│   │   ├── mcp_tool.py                      # MCP integration
│   │   └── sandbox_utils.py                # Sandbox helpers and skill records
│   └── utils/
│       └── path.py                          # Project root path helper
├── client/                                  # React frontend (built separately)
│   └── src/
│       ├── components/chat/                 # Chat UI components
│       ├── contexts/                        # StreamContext, ThreadContext
│       ├── hooks/                           # useStream, useAutoScroll, useThreads
│       ├── api/                             # API client + SSE stream parser
│       └── lib/                             # TypeScript types and helpers
├── AGENTS.md                                # Agent system prompt and conventions
├── Dockerfile                               # Multi-stage build (frontend + backend)
├── docker-compose.yml                       # Full stack (app + Redis + MongoDB)
└── .github/workflows/build-image.yml        # CI: build on GitHub Release

The Dockerfile uses a multi-stage build:

1. Stage 1 (node:22-alpine) — builds the React frontend into client/dist/
2. Stage 2 (python:3.11-slim) — installs Python dependencies, copies the frontend build, and serves everything with Uvicorn on port 8000

In production, the frontend is served directly by FastAPI — no separate web server needed.

Pull the pre-built image or build locally, then start the full stack:

# Clone the repository
git clone https://github.com/arixse/MiloAgentServer.git
cd MiloAgentServer

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start all services (app + Redis + MongoDB)
docker compose up -d

The app is available at http://localhost:8000. The compose file includes:

All services are connected via an internal milo-net bridge network. Redis and MongoDB data are persisted in named volumes.

To update to a new version:

git pull
docker compose up -d --build

Creating a GitHub Release triggers an automatic build and push to GHCR. To deploy with the pre-built image:

# Pull the image
docker pull ghcr.io/arixse/milo-agent-server:latest

# Start Redis and MongoDB separately
docker run -d --name milo-redis -p 6379:6379 redis:7-alpine
docker run -d --name milo-mongo -p 27017:27017 mongo:7

# Start the app
docker run -d \
  --name milo-agent \
  -p 8000:8000 \
  --env-file .env \
  -e REDIS_HOST=host.docker.internal \
  -e MONGO_URI=mongodb://host.docker.internal:27017 \
  ghcr.io/arixse/milo-agent-server:latest

Prerequisites: Python 3.11+, Node.js 22+, Redis, MongoDB.

# Build the frontend
cd client
npm install && npm run build
cd ..

# Install Python dependencies
uv sync --no-dev

# Start the server
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000

Place the app behind a reverse proxy (nginx, Caddy) for TLS termination:

# Example nginx configuration
server {
    listen 443 ssl;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;  # Required for SSE streaming
    }
}

• Each thread gets its own isolated OpenSandbox instance (opensandbox/code-interpreter:v1.0.2)
• Sandboxes are automatically renewed in the background (default 24h timeout)
• On server restart, sandboxes are reconnected via Redis mappings
• Thread deletion or server shutdown cleans up the associated sandbox
• pip is automatically installed during sandbox initialization via a three-tier fallback (built-in pip → ensurepip → apt-get)

Skills are zip archives installed into the sandbox's /skills/ directory:

1. Agent calls install_skill with a skill name and download URL
2. The zip is downloaded, uploaded to the sandbox, and extracted
3. Installation records are persisted in Redis per user
4. If a sandbox is destroyed and recreated, all skills are automatically restored