Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Docker support in Serena is an experimental feature designed to run the system in an isolated container environment. This approach enhances security, particularly for shell tool execution, and ensures consistent dependencies across different host operating systems such as Windows, macOS, and Linux.
The deployment leverages Docker Compose for managing services and volume mounts, allowing Serena to operate as a Model Context Protocol (MCP) server while providing a web-based dashboard for monitoring and configuration.
Sources: DOCKER.md:1-12, README.md:104-107
Architecture and Components
The Docker architecture separates the Serena application from the host system, utilizing specific port mappings for communication and volume mounts for data persistence.
The diagram shows the relationship between the host system and the isolated Serena container, including port exposure and volume mounting points.
Sources: DOCKER.md:15-18, DOCKER.md:94-98
Key Benefits of Containerization
- Safer Shell Execution: Commands are restricted to the containerized environment.
- Dependency Management: Language servers and system dependencies are pre-configured within the image.
- Isolation: Project configuration and logs are kept separate from the host system.
Sources: DOCKER.md:9-13
Deployment Modes
Serena supports two primary deployment methods via docker-compose.yaml or manual docker commands.
Docker Compose
Docker Compose provides two pre-defined profiles for different use cases:
| Service Name | Description | Command / Entrypoint |
|---|---|---|
serena | Production mode; runs Serena as an MCP server. | uv run serena-mcp-server |
serena-dev | Development mode; typically mounts source code for active development. | N/A |
Sources: DOCKER.md:81-88, compose.yaml
Manual Execution
Users can build and run the image manually using standard Docker CLI commands. The application requires specific environment variables and port mappings to function correctly as an MCP server.
# Build the image
docker build -t serena .
# Run with environment flags
docker run -it --rm \
-v "$(pwd)":/workspace \
-p 9121:9121 \
-p 24282:24282 \
-e SERENA_DOCKER=1 \
serena
Sources: DOCKER.md:91-100, docker_build_and_run.sh
Configuration and Persistence
Serena stores its configuration and session logs in the container at /workspaces/serena/config/. To persist settings across container restarts, this directory must be mounted to a local directory.
Docker-Specific Requirements
When running in Docker, the following configuration settings in serena_config.yml are mandatory:
gui_log_window: False: Disables the GUI log window which is unsupported in headless containers.web_dashboard_listen_address: 0.0.0.0: Ensures the dashboard is accessible from outside the container.web_dashboard_open_on_launch: False: Prevents attempts to open a browser inside the container.
Sources: DOCKER.md:19-35
Port Configuration
The dashboard and MCP server ports can be customized via environment variables:
| Variable | Default Value | Description |
|---|---|---|
SERENA_PORT | 9121 | Port for the MCP server. |
SERENA_DASHBOARD_PORT | 24282 | Port for the web dashboard (0x5EDA). |
SERENA_DOCKER | 1 | Automatically set to indicate a Docker environment. |
Sources: DOCKER.md:65-71, DOCKER.md:113-116
Volume Mounting and Project Access
Because the container is isolated, projects must be explicitly mounted as volumes to be accessible to Serena's tools.
The sequence demonstrates the requirement for manual volume mapping before project activation within the container.
Sources: DOCKER.md:39-44, DOCKER.md:105-110
Limitations
- Project Visibility: Only directories mounted as volumes can be accessed or activated.
- Language Support: The default image does not include system-level dependencies for all languages; only those that install requirements "on the fly" work immediately.
- Windows Line Endings: Files edited in the container use Unix (LF) endings, which may conflict with Windows (CRLF) host settings.
Sources: DOCKER.md:38-62
Web Dashboard Integration
The web dashboard provides a frontend for monitoring the containerized instance. It communicates with the backend via various endpoints to fetch logs, tool statistics, and configuration status.
| Endpoint | Method | Description |
|---|---|---|
/get_config_overview | GET | Fetches current container configuration and active projects. |
/get_log_messages | POST | Retrieves log messages for the dashboard log container. |
/shutdown | PUT | Terminates the Serena server. |
Sources: src/serena/resources/dashboard/dashboard.js:338-341, src/serena/resources/dashboard/dashboard.js:655-658, src/serena/resources/dashboard/dashboard.js:1248-1251
Conclusion
Docker deployment for Serena offers a secure and consistent environment for AI agents to interact with codebases. While experimental, it provides the necessary infrastructure for isolated shell execution and MCP server functionality, provided that volume mounts and network configurations are correctly established by the user.