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#

bash

agentpass tools

Execute a tool#

bash

agentpass request <tool_name> [key=value ...]

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:

bash

agentpass request ha_get_state entity_id=light.living_room

Get all entity states:

bash

agentpass request ha_get_states

List available HA services and their fields:

bash

agentpass request ha_get_services

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

bash

agentpass request ha_get_history entity_id=sensor.temperature

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

bash

agentpass request ha_get_logbook entity_id=light.living_room

Get Home Assistant configuration:

bash

agentpass request ha_get_config

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:

bash

# exec with background: false
agentpass request ha_call_service domain=light service=turn_on entity_id=light.living_room
agentpass request ha_call_service domain=light service=turn_on entity_id=light.bedroom brightness=128 color_name=red
agentpass request ha_call_service domain=switch service=toggle entity_id=switch.fan
agentpass request ha_call_service domain=climate service=set_temperature entity_id=climate.thermostat temperature=21

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

Render a Home Assistant template:

bash

# exec with background: false
agentpass request ha_render_template template="{{ states('sensor.temperature') }} degrees"

Always denied (blocked by policy)#

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

Important Notes#

• entity_id 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, color_name, rgb_color, temperature, hvac_mode).