Automation
ZoarkBot runs scheduled tasks, responds to emails, and reacts to external events automatically. Three systems power this: Cron, Email Intelligence, and Webhooks.
⏰ Scheduled Jobs (Cron)
Cron is Zero's built-in scheduler. Jobs persist across restarts and wake the agent at the right time. Think of a cron job as: when to run + what to do.
One-Shot
Run once at a specific time — perfect for reminders.
--at "2026-06-01T09:00:00Z"Recurring
Run on a schedule using cron expressions or intervals.
--cron "0 8 * * *"Isolated
Runs in its own session — won't clutter your main chat.
--session isolatedCLI Examples
zoarkbot cron add \ --name "Send reminder" \ --at "2026-01-12T18:00:00Z" \ --session main \ --system-event "Reminder: submit expense report." \ --wake now \ --delete-after-run
zoarkbot cron add \ --name "Morning briefing" \ --cron "0 8 * * *" \ --tz "America/New_York" \ --session isolated \ --message "Give me my morning briefing: email summary, calendar, news." \ --deliver \ --channel telegram
Manage Cron Jobs
| Command | What it does |
|---|---|
| zoarkbot cron list | List all scheduled jobs |
| zoarkbot cron add ... | Create a new cron job |
| zoarkbot cron remove <jobId> | Delete a job |
| zoarkbot cron pause <jobId> | Pause without deleting |
| zoarkbot cron run <jobId> | Run a job immediately |
| zoarkbot cron history <jobId> | View run history |
Job storage: Jobs persist in ~/.zoarkbot/cron/jobs.json so they survive restarts. Run history is saved in ~/.zoarkbot/cron/runs/<jobId>.jsonl.
✉️ Email Intelligence
Zero can read your Gmail inbox, classify emails, draft replies, and send them with your approval. The flow is: email arrives → classify → suggest action → you approve → send.
What Zero Can Do With Email
| Action | Description |
|---|---|
| read_inbox | Fetch recent emails (with optional search query) |
| classify | Label as: meeting request, action required, FYI, spam, newsletter |
| draft_reply | Generate a reply draft for your review |
| send | Send a message after your approval |
| label | Apply a Gmail label (e.g., zaas-lead) |
| archive | Archive a message (removes from inbox) |
| search | Search Gmail with any query string |
| mark_read | Mark a message as read |
Proactive Email Flow
Setup required: Email automation requires a Google OAuth2 refresh token. Go to Mission Control → Settings → Integrations and follow the Gmail setup wizard, or tell Zero: "Set up Gmail OAuth for me".
🔗 Webhooks
External systems can trigger Zero via HTTP webhooks. Use webhooks to wake Zero from external events (GitHub push, form submission, Zapier, etc.).
Enable Webhooks
# In zoarkbot.json
{
"hooks": {
"enabled": true,
"token": "your-secret-token",
"path": "/hooks"
}
}Endpoints
/hooks/wakeWake Zero with a system event. Perfect for notifications.
curl -X POST http://localhost:18789/hooks/wake -H 'Authorization: Bearer SECRET' -H 'Content-Type: application/json' -d '{"text":"New lead submitted","mode":"now"}'/hooks/agentRun an isolated agent turn and optionally deliver the response.
curl -X POST http://localhost:18789/hooks/agent -H 'Authorization: Bearer SECRET' -H 'Content-Type: application/json' -d '{"message":"Summarize inbox","deliver":true,"channel":"telegram"}'Security tip: Keep webhook endpoints behind a reverse proxy (Caddy/nginx). Use a dedicated hook token — never reuse your gateway auth token. Webhook payloads are sandboxed by default.