The facebox image processing platform allows you to detect and recognize faces in a camera image using Facebox. The state of the entity is the number of faces detected, and recognized faces are listed in the matched_faces attribute. An image_processing.detect_face event is fired for each recognized face, and the event data provides the confidence of recognition, the name of the person, the image_id of the image associated with the match, the bounding_box that contains the face in the image, and the entity_id that processing was performed on.


Facebox runs in a Docker container and it is recommended that you run this container on a machine with a minimum of 2 GB RAM. On your machine with Docker, run the Facebox container with:


sudo docker run --name=facebox --restart=always -p 8080:8080 -e "MB_KEY=$MB_KEY"  machinebox/facebox

or using docker-compose:

version: '3'
    image: machinebox/facebox
    container_name: facebox
    restart: unless-stopped
      - 8080:8080
      - MB_KEY=${MB_KEY}

You can run Facebox with a username and password by adding -e "MB_BASICAUTH_USER=my_username" -e "MB_BASICAUTH_PASS=my_password" but bear in mind that the integration does not encrypt these credentials and this approach does not guarantee security on an unsecured network.

After you created an account at Machinebox, you can grab your MB_KEY at your Account page.

If you only require face detection (number of faces) you can disable face recognition by adding -e "MB_FACEBOX_DISABLE_RECOGNITION=true" in the docker run command.

If your host machine does not support AVX and you experience issues running the machinebox/facebox image there is an alternative image without AVX support available at machinebox/facebox_noavx(HINT: This image is currently not supported by machinebox and should only be used if necessary)


To enable this platform in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
  - platform: facebox
    port: 8080
      - entity_id: camera.local_file
        name: my_custom_name

Configuration Variables

ip_address string Required

The IP address of your machine hosting Facebox.

port string Required

The port which Facebox is exposed on.

username string (Optional)

The Facebox username if you have set one.

password string (Optional)

The Facebox password if you have set one.

source map Required

The list of image sources.

entity_id string Required

A camera entity id to get picture from.

name string (Optional)

This parameter allows you to override the name of your image_processing entity.


Use the image_processing.detect_face events to trigger automations, and breakout the trigger.event.data using a template. The following example automation sends a notification when Ringo Star is recognized:

- id: '12345'
  alias: Ringo Starr recognised
    platform: event
    event_type: image_processing.detect_face
      name: 'Ringo_Starr'
    service: notify.platform
      message: Ringo_Starr recognised with probability {{ trigger.event.data.confidence }}
      title: Door-cam notification

Service facebox.teach_face

The service facebox.teach_face can be used to teach Facebox faces.

Service data attribute Optional Description
entity_id no Entity ID of Facebox entity.
name no The name to associate with a face.
file_path no The path to the image file.

A valid service data example:

  "entity_id": "image_processing.facebox_local_file",
  "name": "superman",
  "file_path": "/images/superman_1.jpeg"

You can use an automation to receive a notification when you train a face:

- id: '1533703568569'
  alias: Face taught
  - event_data:
      service: facebox.teach_face
    event_type: call_service
    platform: event
  condition: []
  - service: notify.pushbullet
      message: '{{ trigger.event.data.service_data.name }} taught
      with file {{ trigger.event.data.service_data.file_path }}'
      title: Face taught notification

Any errors on teaching will be reported in the logs. If you enable system_log events:

  fire_event: true

you can create an automation to receive notifications on Facebox errors:

- id: '1533703568577'
  alias: Facebox error
    platform: event
    event_type: system_log_event
    condition: template
    value_template: '{{ "facebox" in trigger.event.data.message }}'
  - service: notify.pushbullet
      message: '{{ trigger.event.data.message }}'
      title: Facebox error