Codex App for Home Assistant

Run OpenAI Codex from the Home Assistant sidebar.

This repository is a compatible fork of the original kecksdigital/codex-hass App. It keeps the original codex add-on slug and persistent paths while carrying a different image update strategy; see MIGRATION.md for the changes and upgrade path.

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.

Why This Fork

The original App can leave Codex unusable after a runtime npm update: writable Home Assistant mounts are not executable, while the image-installed CLI cannot be replaced by the unprivileged terminal user. This fork installs a pinned Codex CLI in the image, disables runtime npm updates, and keeps the codex slug, App options, and persistent state paths so an existing installation can upgrade in place.

Read MIGRATION.md before switching repositories. It explains the exact changes, backup-first upgrade steps, and rollback path.

Install

Manual install:

1. Open Settings -> Add-ons -> Add-on Store in Home Assistant.
2. Open Repositories from the three-dot menu.
3. Add https://github.com/CaneTLOTW/ha-codex.
4. Install Codex.
5. Start the App and open it from the sidebar.

What You Get

• 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 /ssl and /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.

Authentication

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.

Defaults

• 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.

Updates

Home Assistant updates the Codex App when this repository publishes a higher version in codex/config.yaml.

A daily GitHub Actions check updates main when npm publishes a newer @openai/codex release. It updates the image pin, increments the App patch version, and starts the image publication workflow.

The App uses prebuilt images from GitHub Container Registry:

ghcr.io/canetlotw/ha-codex:<version>

Automatic updates: Enable Auto update on the Codex App page in Home Assistant. Home Assistant then installs newly published App images automatically. This is separate from the legacy auto_update_codex option, which must remain disabled because runtime npm updates are unsupported.

Documentation

Read the full usage guide in codex/README.md.

Useful upstream docs:

• Codex CLI
• Codex authentication
• Codex configuration
• Codex configuration reference

Support

• Issues
• Home Assistant Community

License

MIT License