Appearance
Tasks
A task is an agent, an instruction and what starts it:
- a schedule: "every weekday at 09:00, check the status page and tell me if anything is wrong";
- a webhook another service calls: "whenever a pull request is opened on GitHub, review it";
- watching an integration: "when a new email from a customer arrives, draft a reply".
Asking an agent
The quickest way is to say it in a chat: "every morning at 8, send me a brief of my day", or "when a pull request is opened, review it for security issues". The agent proposes the task in the conversation: its name, what starts it, the instruction it will follow and when you'll be notified. Nothing exists until you click Create task, or Edit first to change anything (the schedule, the events, the instruction) before creating it. A schedule the agent gave no time zone uses yours. Ask for the result to be sent to you ("send me…", "by email") and the task emails you each one (see Being told).
The same happens while you set up an agent by chatting: mention that the job should run on its own ("every morning at 8") and the agent proposes the task beside its role, instead of writing the time into its instructions, where nothing would run it. Apply the role first, then create the task.
The agent can't create tasks on its own: something it reads (a web page, an email, a ticket) could otherwise get it to schedule work that runs as you. Once created, the task is on your Tasks page like any other.
Changing a task works the same way: "move my morning brief to 9", "only tell me when something goes wrong", "pause the PR reviews", "delete the weekly report". The agent looks up your tasks on it and shows the change in the conversation, with what it was and what it becomes. Nothing changes until you click Apply. It can only touch your own tasks, and only those on itself.
Creating one yourself
Tasks → New task, or Schedule on an agent page. You choose:
- the agent: any published agent you can use;
- the instruction: exactly what you would have typed in chat;
- what starts it: a schedule, a webhook, or something new in an integration (below).
On a schedule
A preset (hourly, daily, weekdays, weekly, monthly) or a cron expression, always with a time zone, so "09:00" stays 09:00 across daylight-saving changes. A preview shows the next few runs before you save. Runs are at least five minutes apart.
When a service calls (webhooks)
Choose who calls (GitHub, GitLab, Sentry, Grafana, Jira, or anything else) and which of its events start a run, for instance pull_request.opened. Once the task is created, its page shows:
- a URL to give the other service, and a secret. GitHub and GitLab are given the secret too, and CrewHall refuses their calls without the right signature; for the others the URL is the secret, so keep it to yourself. New URL and secret replaces both if they leak;
- the steps to set it up on the other side;
- What reached it: every call, including the ones that started nothing (another event, GitHub's ping when you add the webhook, a paused task), so you can see that the setup works.
The agent receives the instruction followed by the call's content (trimmed of links and noise). That content was written by someone else, and the agent is told never to follow instructions found in it.
For anything else, POST JSON to the URL. Name the event in an X-CrewHall-Event header (or an event or type field) if you want to filter on it, and sign the body with HMAC-SHA256 in X-CrewHall-Signature: sha256=<hex> if you like:
bash
curl -X POST https://crewhall.example.com/api/hooks/<token> \
-H 'content-type: application/json' \
-d '{"event": "deploy", "service": "api", "version": "1.4.2"}'The server must be reachable
Other services call CrewHall's public address. On a laptop (localhost) they can't reach it: the task page says so. Use a server, or a tunnel to try it.
When something new appears (watching)
Choose one of the agent's integrations (Gmail, Slack, Jira, GitHub…), one of its tools that reads (a search, a list), the arguments to call it with (a search query, a project), and how often to check (every 5 minutes to once a day). Try it now shows what it returns today.
The first check notes what's already there. After that, each check compares the results with what it has seen, and starts a run only when something is new; the agent receives the new results with the instruction. Checking doesn't use the model, so a quiet watch costs nothing. It checks with your account when the integration uses each person's own, so you must have connected it (Account → Connections). Five failed checks in a row pause the task, with the reason.
Results are told apart by their id (a message id, an issue key) when they have one, otherwise by their content, so a tool whose output changes every time (a clock, "5 minutes ago") will look new at every check. Pick a tool and arguments that list items.
It runs as you
A task runs with your identity and access: your usage, your budget, your integration connections. Treat it as a message you sent yourself.
Before each run CrewHall re-checks that you still have access and that the agent is still publishable. If something has changed (the agent was archived, your access was removed, the model was disabled), the task is paused with the reason, and you are told. Fix it and resume.
Where runs live
Each task has its own conversation. Every run adds the instruction (and the event that started it) and the report to it, so you can read the whole history, see the tool cards, and reply to follow up on anything. On the task page, each run says which event started it.
Each run starts fresh from the instruction: it does not remember the last one. Anything that should carry over belongs in the agent's memory.
Being told
Per task:
- after every run: for a short digest you want to read;
- only when it fails: for something that is usually quiet;
- when the agent decides: the agent gets a tool to raise a flag, and only uses it when something is worth your attention. Needs a model that supports tools.
Failures and automatic pauses always notify, whatever you choose.
Email me each result sends you each successful run's whole answer by email, whatever you chose for notifications: for a morning brief or a weekly report you'd rather read in your inbox. It needs a server that sends email.
Notifications show under the bell. To get them by email too, choose under Account → Email notifications, kind by kind: at once, in one email a day around 8:00 your time listing what you haven't read yet, or not at all. Unless you change it, approvals waiting and task problems (a failed run, a paused task) come by email at once, and nothing else does.
On Telegram
Your notifications can also come from your own Telegram bot, with Approve and Reject buttons under what agents ask: see Telegram.
Keeping it bounded
Each run has a time limit: 10 minutes unless you change it (Edit → Limits per run → Time limit, from 1 minute to 24 hours). A run still working when it's reached fails, with "timed out" as the reason, and you're notified like for any failure. Time spent waiting for you to approve something doesn't count. A task can also have its own limit on model calls (up to the server's 50) and tokens per run: at either, or the model's own limit per answer, the agent answers with what it found so far and says it was cut short. Monthly budgets apply as they do everywhere else.
- Schedules: if the server is down over a scheduled time, the run happens once when it comes back, not once per missed slot. If the previous run is still going, the occurrence is skipped and recorded.
- Events (webhooks and watching) wait their turn: if a run is going, the next event starts when it ends, so five pull requests opened at once make five runs, one after the other. A task starts at most 30 runs an hour; at most 20 events wait, and an event waiting more than a day is dropped. Calls while the task is paused are logged and start nothing.
Run now (Run again once it has run) starts it immediately, even while paused (without an event), from the task's page or its row in Tasks. Only you can run your tasks; an administrator can list and pause them, but not run them.
When a run fails, stops or is skipped, the task list, the task page and the failure notification say why in a word: Timed out, Call limit reached, Token limit reached, Budget used up, Model error, Model rate-limited, Model unreachable, Model key rejected or Server restarted, with the full message on the run.
Stop, in the same places while a run is going, and in the task's conversation, ends it: what the agent said so far stays in the conversation, the run is marked stopped (not failed, so nobody is notified), and the next waiting event starts. It also works on a run the server lost track of, so a task is never stuck "running": you, the people who manage the agent's space, and administrators can stop one.

