Build optimized energy management plans for your home automation

AkkudoktorEOS is a comprehensive solution for simulating and optimizing energy systems based on renewable sources. Optimize your photovoltaic systems, battery storage, load management, and electric vehicles while considering real-time electricity pricing.

Why use AkkudoktorEOS?

AkkudoktorEOS can be used to build energy management plans that are optimized for your specific setup of PV system, battery, electric vehicle, household load and electricity pricing. It can be integrated into home automation systems such as NodeRED, Home Assistant, EVCC.

🏘️ Community

We are an open-source community-driven project and we love to hear from you. Here are some ways to get involved:

• GitHub Issue Tracker: discuss ideas and features, and report bugs.

• Akkudoktor Forum: get direct suppport from the community.

What do people build with AkkudoktorEOS

The community uses AkkudoktorEOS to minimize grid energy consumption and to maximize the revenue from grid energy feed in with their home automation system.

• Andreas Schmitz, the Akkudoktor, uses EOS integrated in his NodeRED home automation system for OpenSource Energieoptimierung.
• Jörg, meintechblog, uses EOS for day-ahead optimization for time-variable energy prices. See: So installiere ich EOS von Andreas Schmitz

Why not use AkkudoktorEOS?

AkkudoktorEOS does not control your home automation assets. It must be integrated into a home automation system. If you do not use a home automation system or you feel uncomfortable with the configuration effort needed for the integration you should better use other solutions.

Quick Start

Upgrading an existing installation?

The next release includes a substantial energy-planning update: 15-minute GENETIC plans, EV departure targets, flexible household loads, optional battery export, and better measurement and PV-forecast tools. These features are currently unreleased.

Existing Home Assistant automations, Node-RED flows and custom API clients may need changes. Devices now use stable IDs, the new optimizer reads hardware settings from EOS configuration, and incomplete forecasts or outdated battery measurements can stop a run. The legacy POST /optimize remains available with GENETIC0; the new POST /v1/optimize has a different request format. Back up your configuration and data before updating.

Read the upgrade guide and changelog before switching an existing installation.

Start with Docker

Run EOS with Docker (access dashboard at http://localhost:8504):

docker run -d \
  --name akkudoktoreos \
  -p 8503:8503 \
  -p 8504:8504 \
  -e OPENBLAS_NUM_THREADS=1 \
  -e OMP_NUM_THREADS=1 \
  -e MKL_NUM_THREADS=1 \
  -e EOS_SERVER__HOST=0.0.0.0 \
  -e EOS_SERVER__EOSDASH_HOST=0.0.0.0 \
  -e EOS_SERVER__EOSDASH_PORT=8504 \
  --ulimit nproc=65535:65535 \
  --ulimit nofile=65535:65535 \
  --security-opt seccomp=unconfined \
  akkudoktor/eos:latest

System Requirements

• Python: 3.11 or higher
• Architecture: amd64, aarch64 (armv8)
• OS: Linux, Windows, macOS

Note

: Other architectures (armv6, armv7) require manual compilation of dependencies with Rust and GCC.

Installation

Home Assistant add-on

To install the Akkudoktor-EOS add-on in Home Assistant:

1. Add the repository URL:

   In Home Assistant, go to:

   Settings → Add-ons → Add-on Store → ⋮ (top-right menu) → Repositories
   

   and enter the URL of this Git repository:

   https://github.com/Akkudoktor-EOS/EOS
   

2. Install the add-on:

   After adding the repository, the add-on will appear in the Add-on Store. Click Install.

3. Start the add-on:

   Once installed, click Start in the add-on panel.

4. Access the dashboard:

   Click Open Web UI in the add-on panel.

5. Configure EOS (optional): In the dashboard, go to:

   Config
   

Docker (Recommended)

1. create docker compose file:

services:
  eos:
    image: akkudoktor/eos:latest
    container_name: akkudoktoreos
    restart: unless-stopped
    environment:
      - OPENBLAS_NUM_THREADS=1
      - OMP_NUM_THREADS=1
      - MKL_NUM_THREADS=1
      - EOS_SERVER__HOST=0.0.0.0
      - EOS_SERVER__PORT=8503
      - EOS_SERVER__EOSDASH_HOST=0.0.0.0
      - EOS_SERVER__EOSDASH_PORT=8504
      # Change this to a random secret, e.g. output of: openssl rand -hex 32
      - EOS_SERVER__EOSDASH_SESSKEY=change-me
    ports:
      - "8503:8503"   # EOS API
      - "8504:8504"   # EOSdash
    volumes:
      - ./data:/data

2. create a .env file with the secret:

echo "EOS_SESSKEY=$(openssl rand -hex 16)" > .env

3. pull image and start:

docker pull akkudoktor/eos:latest
docker compose up -d

4. Access EOS:

   • API: http://localhost:8503
   • API docs: http://localhost:8503/docs
   • EOSdash: http://localhost:8504

Configuration and data are stored in ./data.

Note: The docker-compose.yaml in the repository root is intended for development (it builds the image locally and relies on the repository's .env). Use the file above if you only want to run the published image.

From Source

git clone https://github.com/Akkudoktor-EOS/EOS.git
cd EOS

Linux:

python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
.venv/bin/python -m akkudoktoreos.server.eos

Windows:

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\pip install -e .
.venv\Scripts\python -m akkudoktoreos.server.eos

Configuration

EOS uses EOS.config.json for configuration. If the file doesn't exist, a default configuration is created automatically.

Custom Configuration Directory

export EOS_DIR=/path/to/your/config

Configuration Methods

1. EOSdash (Recommended) - Web interface at http://localhost:8504
2. Manual - Edit EOS.config.json directly
3. API - Use the Server API

See the documentation for all configuration options.

Port Configuration

Default ports: 8503 (API), 8504 (Dashboard)

If running on shared systems (e.g., Synology NAS), these ports may conflict with system services. Reconfigure port mappings as needed:

docker run -p 8505:8503 -p 8506:8504 ...

API Documentation

Interactive API docs available at:

• Swagger UI: http://localhost:8503/docs
• OpenAPI Spec: View Online

Resources

• Full Documentation
• Installation Guide (German)

Contributing

We welcome contributions! See CONTRIBUTING for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.