Agents

Agents are registered CLI instances that execute cron jobs locally on their host machines. Register your CLI as an agent to run scheduled commands and sync results with the cloud.

What is an Agent?

An agent is a named CLI instance tied to a specific hostname. When you create cron jobs, they are assigned to an agent that executes the commands locally. The agent syncs execution results, logs, and status back to the HookWatch cloud.

Local Execution

Commands run directly on the agent's host machine with full access to local tools and files.

Cloud Sync

Execution results, stdout/stderr, and status are synced to the cloud for monitoring in the dashboard.

Heartbeat

Agents send periodic heartbeats so you can monitor their availability (online/offline).

Register an Agent

Register your CLI as a named agent. The agent name and ID are saved to your local config file.

Terminal

Auto-registration

On first use, the CLI will prompt you to register as an agent if no agent is configured. You can also register at any time with hookwatch agent register.

List Agents

View all registered agents for your account:

Terminal

Agent Details

View detailed information about a specific agent, or the current agent if no argument is given:

Terminal
Terminal

Remove an Agent

Remove a registered agent by name or ID:

Terminal

Warning

Removing an agent will unassign it from any cron jobs. Those jobs won't execute until reassigned to another agent.

Aliases

You can use agents as a shortcut:

hookwatch agents list

The remove command also accepts rm and delete as aliases.

Using Agents with Cron Jobs

After registering an agent, you can assign cron jobs to it and run the cron service daemon:

1. Register your agent

hookwatch agent register my-server

2. Create a cron job

hookwatch cron add "backup" --schedule "every day at 2am" --command "pg_dump mydb > backup.sql"

3. Start the cron service

hookwatch cron service install && hookwatch cron service start

Related