---
title: "Working with tasks"
description: "How DrowAI tasks represent scoped, interactive pentesting work sessions."
section: "Workflow"
updated: 2026-06-18
tags: ["tasks","workflow"]
source: "/user-guide/working-with-tasks"
---

# Working with tasks

How DrowAI tasks represent scoped, interactive pentesting work sessions.

A task is the active unit of work in DrowAI. It gives the operator a scoped
session for running an assessment step, reviewing output, and collecting
material that may become knowledge or report input.

## Create a task

The task form captures the basic operating context:

- Task name.
- Optional description.
- Engagement. If no engagement is selected, DrowAI creates one automatically using the task name and description.
- Target scope.
- Optional text or Markdown scope file.
- Optional VPN configuration for an approved lab or customer environment.

After creation, DrowAI prepares a task workspace and runtime context. A task
name must be unique among currently active tasks for the same user and tenant.

## What task creation affects

Creating a task does more than add an item to the task list:

- It attaches the task to an engagement, creating one automatically when none is selected.
- It creates a task lifecycle record with status, timestamps, scope, retry, timeout, and priority settings.
- It creates a task-local workspace for scope, configuration, logs, artifacts, results, reports, and runtime communication files.
- It prepares that workspace for the runtime environment, where the task workspace is available as `/workspace`.
- It stores VPN configuration for the task when VPN is enabled.
- It queues runtime startup and begins provisioning the task execution environment.
- It invalidates related task and engagement knowledge views so the UI can reflect the new task.
- It prewarms the task chat session on a best-effort basis after successful creation.

In a local DrowAI runtime, the task execution environment is a Docker-backed
Kali container. That container is task-bound: it receives the task workspace,
uses the task scope and configuration, and is the environment used for shell
access, runtime commands, tool execution, logs, metrics, and artifacts.

## Start and control work

Tasks move through lifecycle states such as created, queued, starting, running,
pausing, paused, resuming, stopping, stopped, completed, failed, or timed out.
The visible state tells the operator whether the task is waiting, active,
paused, stopping, finished, or needs attention.

The task card exposes actions that are valid for the current state. A created
task can be started. A running task can be paused or stopped. A paused task can
be resumed or stopped. A stopped task cannot be resumed; create a new task to
run the work again.

Startup includes provisioning the runtime environment. If local Docker is used,
this means creating and starting the task's Kali container, mounting the task
workspace, initializing the container-side workspace paths, applying VPN setup
when configured, and collecting runtime environment information.

## Interact with DrowAI

During a task, the operator can ask DrowAI for help, choose a provider/model,
review streamed activity, answer clarification prompts, approve or skip tool
actions when requested, inspect workspace files, and use shell access where it
is available. The product should be presented as operator-directed and
review-driven, not as unsupervised automatic compromise.

The task workspace is the shared place where runtime output becomes visible to
the product. File Explorer reads from this workspace. Knowledge and reporting
features use durable evidence, tool execution records, artifacts, and task
history derived from task activity.

## Stop a task

Stop a task when useful runtime activity is complete. Stopping retires the
runtime resources for the task, including container and stream state, while
preserving durable task records and review material.

A stopped task can become a reporting input only when DrowAI can confirm that
the runtime was retired and that the task produced useful runtime activity,
such as tool output, artifacts, chat events, or other execution signals. Durable
evidence can continue to support Knowledge review after the runtime is stopped.

## Delete with care

Deleting a task is different from stopping it. Stop work first, then make sure
useful knowledge, files, evidence, and report inputs have been preserved before
removing a task. Deleting a task also removes that task's conversation history,
so keep anything important before deletion.