Tasks

A task is one piece of work for one agent. It names a runner and a workspace, and holds the instructions and events the agent works from. Each task gets a sandbox of its own, which it keeps until it is archived.

Tasks are created from the Web UI, the CLI, an MCP client, a routing rule or a schedule. A task created any of these ways is the same kind of task.

Instructions and runs

A task does its work in runs. A run starts the agent in the task’s sandbox, gives it what is new since the last run, and ends when the agent exits.

• The first run gets the whole task: its instructions, the events that reached it and its links, after gritz’s own instructions on the tools it can use. The workspace’s setup commands run before it, once per sandbox.
• Later runs get only the instructions and events added since the previous run, and the agent continues the session it had: it remembers what it did before.

Two things start a run:

• An instruction. Sending one from the task page, gritz task update -i, or an MCP client starts the task again. If the task is running, the instruction doesn’t interrupt it: the task runs again as soon as the current run ends.
• An event. An event on a resource the task is subscribed to, such as a review comment on its pull request, starts it the same way, if the routing rule that matched the event wakes tasks.

Agents don’t stop by themselves to ask for input. A task that needs an answer from you completes, and the agent says what it needs in its report or on the pull request or issue it is working on. Your next instruction, or a reply on a resource the task is subscribed to, starts the next run.

The diagram follows a task on a Docker runner from its creation to the end of its first run: the runner picks it up and starts its sandbox, and the driver there runs the agent and reports the run’s status to the server.

Open the create-task diagram

Statuses

Status
draft	Created without starting. Tasks created in the Web UI start as drafts, until you send the first instruction.
pending	Waiting for its runner to start the run. A task stays pending while its runner is offline.
running	The agent is running.
restarting	A restart was requested; the runner is stopping the current run to start a new one.
cancelling	A cancel was requested; the runner is stopping the run.
completed	The last run ended normally.
failed	The last run failed: a setup command failed, the agent exited with an error, or the sandbox stopped unexpectedly. The reason is on the timeline.
cancelled	The last run was cancelled.

completed, failed and cancelled are the finished statuses. A finished task isn’t over: an instruction or an event starts it again, from where it left off.

Next to the status, the Web UI shows the task’s pending command, if any: command:start, command:restart or command:stop. It is what the runner has been asked to do and hasn’t done yet. A command:start on a running task is an instruction or event waiting for the current run to end.

Restarting and cancelling

• Restart runs the task again. The agent continues its session, and is told to carry on if nothing new has arrived. On a running task it stops the current run first, so use it when an agent is stuck. It is available on running and finished tasks.
• Cancel stops the task. A pending task is cancelled at once; a running or restarting one goes through cancelling while the runner stops the agent. The sandbox is kept, so the task can still be started again.

Archiving

Archive a task when you are done with it. Archiving:

• destroys its sandbox, and with it any files the agent left there;
• removes it from the task list (turn on Show archived to see it);
• stops events from reaching it: an event on one of its links no longer wakes it, and a routing rule that creates tasks creates a new one instead.

A task can be archived when it is finished or a draft, and has no pending command. Unarchive brings it back to the task list, but not its sandbox.

Auto-archive

A task’s auto-archive delay archives it automatically once it has been finished for that long. The default is never. Immediately archives it as soon as it finishes, which suits tasks whose result lives elsewhere, such as a pull request. The delay counts from the task’s last change, so a task that is woken up again starts over. The server checks for due tasks about once a minute.

Set it when you create the task, in the task page’s sidebar, with --auto-archive on the CLI, on a routing rule that creates tasks, or on a schedule. Unarchiving a task sets its delay back to never. Agents can’t change their own task’s delay.

The timeline and the log

Each task has two records, both on its page in the Web UI:

• The timeline is what happened to the task: instructions, events, the agent’s reports, links, status changes and who caused them. Agents read the same instructions and events with get_my_task.
• The log is the sandbox’s output: setup commands, the agent’s messages and tool calls, and gritz’s own logging. It stays readable after the sandbox is gone, in the Web UI and with gritz logs. Credentials declared as secrets are masked in it.