diff --git a/config_entity_example/config/config_entity_example.robot.marvin.yml b/config_entity_example/config/config_entity_example.robot.marvin.yml
new file mode 100644
index 0000000..eceaf86
--- /dev/null
+++ b/config_entity_example/config/config_entity_example.robot.marvin.yml
@@ -0,0 +1,12 @@
+# This file defines a default config entity. This allows the module to include
+# config entities that are present 'out of the box'.
+# These can be edited by the user. The modified version is saved to the site
+# config folder, which this original copy remains untouched.
+
+# For this system to work, we have to define our config schema in
+# config/config_entity_example.robot.marvin.yml.
+
+# The id of the config entity.
+id: marvin
+# Our properties follow.
+label: 'Marvin, the paranoid android'
diff --git a/config_entity_example/config/schema/config_entity_example.schema.yml b/config_entity_example/config/schema/config_entity_example.schema.yml
new file mode 100644
index 0000000..38fcdce
--- /dev/null
+++ b/config_entity_example/config/schema/config_entity_example.schema.yml
@@ -0,0 +1,19 @@
+# Schema for the configuration files of the Config Entity Example module.
+
+# This schema tells the config system how to read our config YML files.
+# See for example the file config/config_entity_example.robot.marvin.yml, which
+# contains our default config entity.
+
+config_entity_example.robot.*:
+  type: mapping
+  label: 'Robot'
+  mapping:
+    id:
+      type: string
+      label: 'Robot id'
+    uuid:
+      type: string
+      label: 'UUID'
+    label:
+      type: label
+      label: 'Label'
diff --git a/config_entity_example/config_entity_example.api.php b/config_entity_example/config_entity_example.api.php
new file mode 100644
index 0000000..75b7830
--- /dev/null
+++ b/config_entity_example/config_entity_example.api.php
@@ -0,0 +1,6 @@
+<?php
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
diff --git a/config_entity_example/config_entity_example.info.yml b/config_entity_example/config_entity_example.info.yml
new file mode 100644
index 0000000..56127ec
--- /dev/null
+++ b/config_entity_example/config_entity_example.info.yml
@@ -0,0 +1,7 @@
+name: 'Config entity example'
+type: module
+description: 'TODO: Description of module'
+package: Example modules
+core: 8.x
+files:
+  - tests/config_entity_example.test
diff --git a/config_entity_example/config_entity_example.local_actions.yml b/config_entity_example/config_entity_example.local_actions.yml
new file mode 100644
index 0000000..f17f626
--- /dev/null
+++ b/config_entity_example/config_entity_example.local_actions.yml
@@ -0,0 +1,5 @@
+config_entity_example_add_action:
+  route_name: robot_add
+  title: 'Add robot'
+  appears_on:
+    - robot_list
diff --git a/config_entity_example/config_entity_example.module b/config_entity_example/config_entity_example.module
new file mode 100644
index 0000000..91eab24
--- /dev/null
+++ b/config_entity_example/config_entity_example.module
@@ -0,0 +1,7 @@
+<?php
+
+/**
+ * @file
+ * Demonstrates how to define a new configuration entity type.
+ */
+
diff --git a/config_entity_example/config_entity_example.routing.yml b/config_entity_example/config_entity_example.routing.yml
new file mode 100644
index 0000000..1bd0050
--- /dev/null
+++ b/config_entity_example/config_entity_example.routing.yml
@@ -0,0 +1,39 @@
+# The routing.yml file defines the paths for our module.
+# Here we define the paths for our entity type's admin UI.
+
+# This is the router item for listing all entities.
+robot_list:
+  path: '/examples/config_entity_example'
+  defaults:
+    # TODO: explain by what magic '_entity_list' turns into using the entity list controller.
+    _entity_list: 'robot'
+    _title: 'Config Entity Example'
+  requirements:
+    # We're not setting any access control on our admin page for simplicity.
+    _access: 'TRUE'
+
+# This is the router item for adding an entity.
+robot_add:
+  path: '/examples/config_entity_example/add'
+  defaults:
+    _title: 'Add robot'
+    _entity_form: robot.add
+  requirements:
+    _entity_create_access: robot
+
+robot_edit:
+  path: '/examples/config_entity_example/manage/{robot}'
+  defaults:
+    _title: 'Edit robot'
+    _entity_form: robot.edit
+  requirements:
+    # This uses our entity access controller.
+    _entity_access: robot.update
+
+robot_delete:
+  path: '/examples/config_entity_example/manage/{robot}/delete'
+  defaults:
+    _title: 'Delete robot'
+    _entity_form: robot.delete
+  requirements:
+    _entity_access: robot.delete
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php b/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php
new file mode 100644
index 0000000..e63de30
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Controller/RobotListController.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Drupal\config_entity_example\Controller;
+
+use Drupal\Core\Config\Entity\ConfigEntityListController;
+use Drupal\Core\Entity\EntityInterface;
+
+class RobotListController extends ConfigEntityListController {
+
+  public function buildHeader() {
+    $header['label'] = $this->t('Robot');
+    $header['machine_name'] = $this->t('Machine Name');
+    return $header + parent::buildHeader();
+  }
+
+  public function buildRow(EntityInterface $entity) {
+    $row['label'] = $this->getLabel($entity);
+
+    $row['machine_name'] = $entity->id();
+
+    return $row + parent::buildRow($entity);
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php b/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php
new file mode 100644
index 0000000..961c607
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Entity/Robot.php
@@ -0,0 +1,102 @@
+<?php
+
+/**
+ * @file
+ * Contains Drupal\config_entity_example\Entity\Robot.
+ *
+ * This contains our entity class.
+ *
+ * credits: originally based on code from blog post at
+ * http://previousnext.com.au/blog/understanding-drupal-8s-config-entities
+ */
+
+namespace Drupal\config_entity_example\Entity;
+
+use Drupal\Core\Config\Entity\ConfigEntityBase;
+use Drupal\Core\Entity\EntityStorageControllerInterface;
+use Drupal\Core\Entity\Annotation\EntityType;
+use Drupal\Core\Annotation\Translation;
+
+/**
+ * Defines the robot entity.
+ *
+ * The lines below are a plugin annotation. These define the entity type to the
+ * entity type manager.
+ *
+ * The properties in the annotation are as follows:
+ * TODO: add a @see to the annotation docs, assuming these exist!!!
+ *  - id: The machine name of the entity type.
+ *  - label: The human-readable label of the entity type.
+ *    TODO: explain @Translation.
+ *  - module: The name of the module that provides this.
+ *    TODO: is this necessary?
+ *  - controllers: An array specifying controller classes that handle various
+ *    aspects of the entity type's functionality.
+ *  - config_prefix: This tells the config system the prefix to use for
+ *    filenames when storing entities. This means that the default entity we
+ *    include in our module has the filename
+ *    'config_entity_example.robot.marvin.yml'.
+ *  - entity_keys: TODO.
+ *
+ * @ConfigEntityType(
+ *   id = "robot",
+ *   label = @Translation("Robot"),
+ *   module = "config_entity_example",
+ *   admin_permission = "administer robots",
+ *   controllers = {
+ *     "access" = "Drupal\config_entity_example\RobotAccessController",
+ *     "list" = "Drupal\config_entity_example\Controller\RobotListController",
+ *     "form" = {
+ *       "add" = "Drupal\config_entity_example\Form\RobotAddForm",
+ *       "edit" = "Drupal\config_entity_example\Form\RobotEditForm",
+ *       "delete" = "Drupal\config_entity_example\Form\RobotDeleteForm"
+ *     }
+ *   },
+ *   config_prefix = "config_entity_example.robot",
+ *   entity_keys = {
+ *     "id" = "id",
+ *     "label" = "label"
+ *   },
+ *   links = {
+ *     "edit-form" = "robot_edit",
+ *     "delete-form" = "robot_delete"
+ *   }
+ * )
+ */
+class Robot extends ConfigEntityBase {
+
+  /**
+   * The robot ID.
+   *
+   * @var string
+   */
+  public $id;
+
+  /**
+   * The robot UUID.
+   *
+   * @var string
+   */
+  public $uuid;
+
+  /**
+   * The robot label.
+   *
+   * @var string
+   */
+  public $label;
+
+  /**
+   * {@inheritdoc}
+   *
+   * This defines the URI for our entities.
+   */
+  public function uri() {
+    return array(
+      // TODO docs.
+      'path' => 'examples/config_entity_example/manage/' . $this->id(),
+      'options' => array(),
+    );
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php
new file mode 100644
index 0000000..4bce116
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotAddForm.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Drupal\config_entity_example\Form;
+
+use Drupal\config_entity_example\Form\RobotFormBase;
+
+/**
+ * Class RobotAddForm
+ *
+ * Provides the add form for our Robot entity.
+ *
+ * @package Drupal\config_entity_example\Form
+ */
+class RobotAddForm extends RobotFormBase {
+
+  /**
+   * Returns the actions provided by this form.
+   *
+   * For our add form, we only need to change the text of the submit button.
+   *
+   * @param array $form
+   * @param array $form_state
+   * @return array
+   */
+  protected function actions(array $form, array &$form_state) {
+    $actions = parent::actions($form, $form_state);
+    $actions['submit']['#value'] = t('Create Robot');
+    return $actions;
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php
new file mode 100644
index 0000000..cae11fd
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotDeleteForm.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace Drupal\config_entity_example\Form;
+
+use Drupal\Core\Entity\EntityConfirmFormBase;
+
+/**
+ * Class RobotDeleteForm
+ *
+ * Provides a confirm form for deleting the entity. This is different from the
+ * add and edit forms as it does not inherit from RobotFormBase. The reason for
+ * this is that we do not need to build the same form. Instead, we present the
+ * user with a simple yes/no question. For this reason, we derive from
+ * EntityConfirmFormBase instead.
+ *
+ * @package Drupal\config_entity_example\Form
+ */
+class RobotDeleteForm extends EntityConfirmFormBase {
+
+  /**
+   * The question is used a a title in our confirm form. For delete confirm forms,
+   * this typically takes the form of "Are you sure you want to delete...",
+   * including the entity label.
+   * @return string
+   */
+  public function getQuestion() {
+    return t('Are you sure you want to delete robot %label?', array(
+      '%label' => $this->entity->label()
+    ));
+  }
+
+  /**
+   * The confirm text is used as a the text in the button that confirms the
+   * question posed by getQuestion().
+   * @return string
+   */
+  public function getConfirmText() {
+    return t('Delete Robot');
+  }
+
+  /**
+   * Provides the route name to go to if the user cancels the action. For entity
+   * delete forms, this is typically the route that points at the list controller.
+   * @return array
+   */
+  public function getCancelRoute() {
+    return array(
+      'route_name' => 'robot_list',
+    );
+  }
+
+  /**
+   * The submit handler for the confirm form. For entity delete forms, you use
+   * this to delete the entity in $this->entity.
+   * @param array $form
+   * @param array $form_state
+   * @return \Drupal\Core\Entity\EntityInterface|void
+   */
+  public function submit(array $form, array &$form_state) {
+    // Delete the entity.
+    $this->entity->delete();
+
+    // Set a message that the entity was deleted.
+    drupal_set_message(t('Robot %label was deleted.', array(
+      '%label' => $this->entity->label(),
+    )));
+
+    // Redirect the user to the list controller when complete.
+    $form_state['redirect_route']['route_name'] = 'robot_list';
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php
new file mode 100644
index 0000000..b91ee81
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotEditForm.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Drupal\config_entity_example\Form;
+
+use Drupal\config_entity_example\Form\RobotFormBase;
+
+/**
+ * Class RobotEditForm
+ *
+ * Provides the edit form for our Robot entity.
+ *
+ * @package Drupal\config_entity_example\Form
+ */
+class RobotEditForm extends RobotFormBase {
+
+  /**
+   * Returns the actions provided by this form.
+   *
+   * For the edit form, we only need to change the text of the submit button.
+   *
+   * @param array $form
+   * @param array $form_state
+   * @return array
+   */
+  protected function actions(array $form, array &$form_state) {
+    $actions = parent::actions($form, $form_state);
+    $actions['submit']['#value'] = t('Update Robot');
+    return $actions;
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php
new file mode 100644
index 0000000..399fd55
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/Form/RobotFormBase.php
@@ -0,0 +1,133 @@
+<?php
+
+/**
+ * @file
+ * Contains Drupal\config_entity_example\RobotFormController.
+ */
+
+namespace Drupal\config_entity_example\Form;
+
+use Drupal\Core\Entity\EntityFormController;
+
+/**
+ * Class RobotFormBase
+ *
+ * Typically, we need to build the same form for both adding a new entity,
+ * and editing an existing entity. Instead of duplicating our form code,
+ * we create a base class. Drupal never routes to this class directly,
+ * but instead through the child classes of RobotAddForm and RobotEditForm.
+ *
+ * @package Drupal\config_entity_example\Form
+ */
+class RobotFormBase extends EntityFormController {
+
+  /**
+   * Overrides Drupal\Core\Entity\EntityFormController::form().
+   *
+   * Build the entity add/edit form.
+   *
+   * @param array $form
+   * @param array $form_state
+   * @return array
+   */
+  public function buildForm(array $form, array &$form_state) {
+    // Get anything we need form the base class.
+    $form = parent::buildForm($form, $form_state);
+
+    // Drupal provides the entity to us as a class variable. If this is an existing
+    // entity, it will be populated with existing values as class variables. If
+    // this is a new entity, it will be a new object with the class of our entity.
+    // Drupal knows which class to call from the annotation on our Robot class.
+    $robot = $this->entity;
+
+    // Build the form.
+    $form['label'] = array(
+      '#type' => 'textfield',
+      '#title' => t('Label'),
+      '#maxlength' => 255,
+      '#default_value' => $robot->label(),
+      '#required' => TRUE,
+    );
+    $form['id'] = array(
+      '#type' => 'machine_name',
+      '#title' => t('Machine name'),
+      '#default_value' => $robot->id(),
+      '#machine_name' => array(
+        'exists' => 'contact_category_load',
+      ),
+      '#disabled' => !$robot->isNew(),
+    );
+
+    // Return the form.
+    return $form;
+  }
+
+  /**
+   * Overrides Drupal\Core\Entity\EntityFormController::actions().
+   *
+   * To set the submit button text, we need to override actions().
+   *
+   * @param array $form
+   * @param array $form_state
+   * @return array
+   */
+  protected function actions(array $form, array &$form_state) {
+    // Get the basic actins from the base class.
+    $actions = parent::actions($form, $form_state);
+
+    // Change the submit button text.
+    $actions['submit']['#value'] = t('Save');
+
+    // Return the result.
+    return $actions;
+  }
+
+  /**
+   * Overrides Drupal\Core\Entity\EntityFormController::validate().
+   *
+   * @param array $form
+   * @param array $form_state
+   */
+  public function validate(array $form, array &$form_state) {
+    parent::validate($form, $form_state);
+
+    // Add code here to validate your config entity's form elements.
+    // Nothing to do here.
+  }
+
+  /**
+   * Overrides Drupal\Core\Entity\EntityFormController::save().
+   *
+   * Saves the entity. This is called after submit() has built the entity from
+   * the form values. Do not override submit() as save() is the preferred method
+   * for entity form controllers.
+   */
+  public function save(array $form, array &$form_state) {
+    // Get the entity from the class variable. We don't need to do this, but
+    // it often makes the code easier to read.
+    $robot = $this->entity;
+
+    // Drupal already populated the form values in the entity object. Each
+    // form field was saved as a public variable in the entity class. PHP allows
+    // Drupal to do this even if the method is not defined ahead of time.
+    $status = $robot->save();
+
+    // Grab the URL of the new entity. We'll use it in the message.
+    $uri = $robot->url();
+
+    if ($status == SAVED_UPDATED) {
+      // If we edited an existing entity...
+      drupal_set_message(t('Robot %label has been updated.', array('%label' => $robot->label())));
+      watchdog('contact', 'Robot %label has been updated.', array('%label' => $robot->label()), WATCHDOG_NOTICE, l(t('Edit'), $uri . '/edit'));
+    }
+    else {
+      // If we created a new entity...
+      drupal_set_message(t('Robot %label has been added.', array('%label' => $robot->label())));
+      watchdog('contact', 'Robot %label has been added.', array('%label' => $robot->label()), WATCHDOG_NOTICE, l(t('Edit'), $uri . '/edit'));
+    }
+
+    // Redirect the user to the following path after the save optionation.
+    $form_state['redirect'] = 'examples/config_entity_example';
+  }
+
+}
diff --git a/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php b/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php
new file mode 100644
index 0000000..30cd54b
--- /dev/null
+++ b/config_entity_example/lib/Drupal/config_entity_example/RobotAccessController.php
@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * @file
+ * Contains \Drupal\config_entity_example\RobotAccessController.
+ */
+
+namespace Drupal\config_entity_example;
+
+use Drupal\Core\Entity\EntityAccessController;
+use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Session\AccountInterface;
+
+/**
+ * Defines an access controller for the robot entity.
+ *
+ * The access controller determines access to Robot entities.
+ *
+ * @see \Drupal\config_entity_example\Entity\Robot.
+ */
+class RobotAccessController extends EntityAccessController {
+
+  /**
+   * {@inheritdoc}
+   */
+  public function checkAccess(EntityInterface $entity, $operation, $langcode, AccountInterface $account) {
+    // The $opereration parameter tells you what sort of operation access is
+    // being checked for.
+
+    if ($operation == 'view') {
+      return TRUE;
+    }
+    else {
+      // Other than that, we're going to be insanely lax about access.
+      // Don't try this at home!
+      return parent::checkAccess($entity, $operation, $langcode, $account);;
+    }
+  }
+
+}