Run OpenAI Codex from the Home Assistant sidebar.
This repository publishes one Home Assistant App: Codex. It gives you a browser terminal inside Home Assistant, starts in your Home Assistant configuration directory, and can optionally connect Codex to Home Assistant through MCP.
Manual install:
- Open Settings -> Add-ons -> Add-on Store in Home Assistant.
- Open Repositories from the three-dot menu.
- Add
https://github.com/kecksdigital/codex-hass. - Install Codex.
- Start the App and open it from the sidebar.
- OpenAI Codex CLI running in Home Assistant.
- A web terminal served through Home Assistant ingress.
- Prebuilt GHCR images for faster installs and Home Assistant updates.
- Direct access to
/homeassistant,/share, and/media. - Read-only access to
/ssland/backup. - Optional Home Assistant MCP integration for entity lookup and service calls.
- Persistent Codex auth and settings under
/data/codex-home. - Home Assistant options for model default, sandbox access, MCP, terminal theme, and session persistence.
Codex authentication happens inside the terminal. Home Assistant does not store your OpenAI API key, ChatGPT session, or Codex access token in App options.
On first launch, Codex prompts you to sign in. The Codex CLI supports ChatGPT sign-in for subscription access and API-key sign-in for usage-based access. On headless or remote systems, use the Codex device-code login option if the normal browser callback flow cannot complete.
- Model:
gpt-5.4 - Access:
workspace - Approval policy:
on-request - Session persistence: off for a cleaner first sign-in
- MCP: on
- Auto-update Codex CLI: off
Use full_access only when you want Codex to run with broad local access inside the App container.
Use codex_approval_policy: never only when you want autonomous execution without per-action approval prompts.
Home Assistant updates the Codex App when this repository publishes a higher version in codex/config.yaml.
The App uses prebuilt images from GitHub Container Registry:
ghcr.io/kecksdigital/codex-hass:<version>
Enable Auto update on the Codex App page in Home Assistant if you want Home Assistant to install future App versions automatically.
Read the full usage guide in codex/README.md.
Useful upstream docs:
MIT License