custom-card-devcontainer

A devcontainer for developing and testing Home Assistant custom cards.

Features

• Latest Home Assistant installed from PyPI
• HACS installed automatically (skipped if already up to date)
• Node.js LTS via nvm for building and bundling cards
• Fast Python dependency installation via uv
• go2rtc for full Home Assistant media support
• Compatible with GitHub Codespaces and VS Code Dev Containers

Usage

GitHub Codespaces / VS Code Dev Containers

This repository includes a .devcontainer/devcontainer.json you can use directly or adapt for your own project.

The image is published to the GitHub Container Registry on every tagged release. Images are tagged with the full version (1.2.3), minor version (1.2), and latest.

For reproducible environments, pin to a specific version tag:

docker pull ghcr.io/custom-cards/custom-card-devcontainer:1.2.3

Beta / pre-release images

Pre-release tags (e.g. v1.2.3-beta.1) are published with the exact version and a floating beta tag. The latest tag is not updated for pre-releases.

To test a beta image, use the beta tag or pin to the exact pre-release version:

docker pull ghcr.io/custom-cards/custom-card-devcontainer:beta
docker pull ghcr.io/custom-cards/custom-card-devcontainer:1.2.3-beta.1

For your own custom card project, add a .devcontainer/devcontainer.json:

{
  "image": "ghcr.io/custom-cards/custom-card-devcontainer:1.2.3",
  "forwardPorts": [8123],
  "postCreateCommand": "container setup",
  "remoteUser": "vscode",
  "mounts": [
    "source=${localWorkspaceFolder},target=/config/www/workspace,type=bind,consistency=cached"
  ],
  "runArgs": ["--env-file", "${localWorkspaceFolder}/.env"]
}

Docker

docker run --rm -it \
    -p 8123:8123 \
    -v $(pwd):/config/www/workspace \
    -e LOVELACE_LOCAL_FILES="my-card.js" \
    ghcr.io/custom-cards/custom-card-devcontainer

Environment Variables

Name	Description	Default
HASS_USERNAME	Username of the default Home Assistant user	dev
HASS_PASSWORD	Password of the default Home Assistant user	dev
LOVELACE_LOCAL_FILES	Space-separated list of filenames in /config/www/workspace to register as Lovelace resources	Empty
LOVELACE_REMOTE_FILES	Space-separated list of full URLs for remotely served Lovelace resources (e.g. a local dev server)	Empty

LOVELACE_LOCAL_FILES

Use this for the card file(s) you are actively developing. The files must be present in your workspace, which is mounted at /config/www/workspace.

LOVELACE_LOCAL_FILES="my-card.js other-card.js"

LOVELACE_REMOTE_FILES

Use this for resources served by a separate process (e.g. a Webpack or Rollup dev server). Provide full URLs including host and port.

LOVELACE_REMOTE_FILES="http://localhost:5000/my-card.js http://localhost:5001/other-card.js"

Container Script

Command	Description
container	Set up Home Assistant and launch it
container setup	Perform setup (config, user, HACS, Lovelace resources) without launching
container launch	Launch Home Assistant with hass -c /config -v

hassfest

If you are also developing a custom integration, you can validate it with:

hassfest

This will clone the Home Assistant source on first run (into /usr/src/homeassistant) and run hassfest validation against any integrations found in /config/custom_components.