agentpass — Home Assistant Gateway

Execute Home Assistant actions through a secure approval gateway. Read-only queries execute instantly. State-changing actions (turning lights on/off, calling services) are sent to a human guardian on Telegram for approval before execution.

IMPORTANT: The agentpass request command is a BLOCKING command. For tools that need approval, it will wait up to 15 minutes for the guardian to respond on Telegram. You MUST use background: false when executing agentpass request commands to prevent auto-backgrounding. The command returns the actual execution result once approved, or an error if denied/timed out. Do NOT tell the user to "check Telegram" or "approve the request" — just wait silently for the command to finish and then report the result.

Commands

List available tools

CODEBLOCK0

Execute a tool

CODEBLOCK1

Output is JSON on stdout. Errors go to stderr.
Exit codes: 0 = success, 1 = denied, 2 = timeout, 3 = connection error, 4 = invalid args.

Available Tools

Read-only (auto-approved, instant)

Get a single entity state:

CODEBLOCK2

Get all entity states:

CODEBLOCK3

List available HA services and their fields:

CODEBLOCK4

Get state history for an entity (last 24h):

CODEBLOCK5

Get logbook entries for an entity (last 24h):

CODEBLOCK6

Get Home Assistant configuration:

CODEBLOCK7

Requires human approval (command blocks until resolved)

These commands block until approved or denied. Always use background: false to prevent auto-backgrounding.

Call a Home Assistant service:

CODEBLOCK8

The domain and service args are used for the URL path. All other args (entityid, brightness, colorname, temperature, etc.) are sent as the JSON request body.

Render a Home Assistant template:

CODEBLOCK9

Always denied (blocked by policy)

• - ha_fire_event — firing custom events is blocked
• INLINECODE7 with domain=lock — lock control is blocked

Important Notes

• - entityid format: Always domain.object_id, e.g. light.living_room, sensor.temperature, switch.garden_pump. Must be lowercase with underscores.
• domain/service format: Lowercase with underscores, e.g. light, turn_on, set_temperature.
• Approval timeout: If the human guardian doesn't respond within 15 minutes, the request is automatically denied.
• Discover entities first: If you don't know an entity's ID, run ha_get_states to list all entities, or ha_get_services to see available services and their parameters.
• Service parameters: Use ha_get_services to discover which parameters a service accepts (e.g. brightness, colorname, rgbcolor, temperature, hvacmode).