Connect Your AI Agent to Your Smart Home in 10 Minutes

What You'll Get

After this tutorial, your AI agent (Claude Code, Codex, etc.) can connect to your Home Assistant: check the status of lights and sensors, and turn devices on or off within the scope you approve. It takes about 10 minutes and requires no coding.

Don't have Home Assistant yet? Read the Home Assistant Handbook first. It includes a Docker deployment tutorial.

Before You Start

• Home Assistant is already running, and you can open it in your browser, for example http://192.168.1.20:8123.
• Your agent and Home Assistant are on the same home network (for example, both on the same computer at home). A cloud-hosted agent cannot reach LAN addresses like 192.168.x.x.

Step 1: Create a Long-Lived Access Token

A token works like a key dedicated to the agent. It does not use your login password.

1. Open Home Assistant and click your avatar in the bottom-left corner.
2. Click Security.
3. Scroll to the bottom, find Long-lived access tokens, and click Create token.
4. Give it a name, such as ai-agent, and click OK.
5. Copy the long string that appears immediately. Once you close the window, you will never see it again.

Step 2: Hand the Task to Your Agent

Copy the text below to your agent, replacing the two placeholders with your own values:

The agent will handle these steps on its own: test the connection, store the URL and token in a file on your computer, and tell you how many devices it found.

Step 3: Try It Out

Once connected, ask it in plain language:

• "Is the living room light on right now?"
• "Which temperature sensors are in the house, and what is each reading now?"
• "Turn off the living room light."

Lights and ordinary switches it will control directly. For devices with safety implications, such as door locks, alarms, and garage doors, it will ask you first.

Common Problems

• Error 401: The token was copied incorrectly or has been deleted. Go back to Step 1 and create a new one.
• Connection refused or timeout: The computer the agent runs on cannot reach that URL. Make sure it is on the same network as Home Assistant and that the URL includes :8123.
• Device names don't match: Have it "list all lights" first, then give commands using the names it reports.

Security Reminders

• The token can control devices in your home. Do not post it anywhere public.
• Give the token its own name, and when you no longer need it, go back to the Security page and delete it.
• Do not expose port 8123 directly to the internet just so the agent can connect. For use outside your home, use Home Assistant Cloud or a VPN.

Next Steps

• Want the full contents of this Skill or to download it: Connect Home Assistant (Skill)
• Want to learn more: Home Assistant Handbook