---
title: Tasks | Lightcone
description: Give Northstar an instruction in plain language and it operates a computer to complete it.
---

A **task** is the simplest way to use Northstar. You describe what you want done, and Northstar operates a computer to complete it — seeing the screen, deciding what to click, typing, scrolling, navigating between apps — until the work is done.

For more control over each step, see the [Responses API](/guides/responses-api/index.md). For direct computer control without a model, see the [Computers API](/guides/computers/index.md).

## Start a task

### Streaming (real-time events)

Stream events as Northstar works:

```
from tzafon import Lightcone


client = Lightcone()


for event in client.agent.tasks.start_stream(
    instruction="Open Firefox, go to Wikipedia, search for 'machine learning', and summarize the first paragraph",
    kind="desktop",
):
    print(event)
```

```
import Lightcone from "@tzafon/lightcone";


const client = new Lightcone();


const stream = await client.agent.tasks.startStream({
  instruction: "Open Firefox, go to Wikipedia, search for 'machine learning', and summarize the first paragraph",
  kind: "desktop",
});


for await (const event of stream) {
  console.log(event);
}
```

### Async (fire and forget)

Start a task and get back a `task_id` immediately. Poll for status later.

```
task = client.agent.tasks.start(
    instruction="Open the terminal, check disk usage with df -h, and take a screenshot of the results",
    kind="desktop",
)
print(task.task_id)  # Use this to check status later
```

```
const task = await client.agent.tasks.start({
  instruction: "Open the terminal, check disk usage with df -h, and take a screenshot of the results",
  kind: "desktop",
});
console.log(task.task_id);
```

## Check task status

```
status = client.agent.tasks.retrieve_status(task.task_id)
print(status.status)     # e.g., "running", "completed"
print(status.exit_code)  # 0 on success
```

```
const status = await client.agent.tasks.retrieveStatus(task.task_id!);
console.log(status.status);
console.log(status.exit_code);
```

## Pause and resume

Pause a running task to intervene or save resources, then resume:

```
client.agent.tasks.pause(task.task_id)
# ... do something ...
client.agent.tasks.resume(task.task_id)
```

```
await client.agent.tasks.pause(task.task_id!);
// ... do something ...
await client.agent.tasks.resume(task.task_id!);
```

## Inject a message

Redirect or clarify while Northstar is working:

```
client.agent.tasks.inject_message(
    task.task_id,
    message="Focus on the top 3 results only",
)
```

```
await client.agent.tasks.injectMessage(task.task_id!, {
  message: "Focus on the top 3 results only",
});
```

## Configuration options

| Parameter                            | Default                       | Description                                       |
| ------------------------------------ | ----------------------------- | ------------------------------------------------- |
| `instruction`                        | —                             | Plain language description of the work (required) |
| `kind`                               | —                             | `"desktop"` or `"browser"` (required)             |
| `model`                              | `"tzafon.northstar-cua-fast"` | Which Northstar model to use                      |
| `max_steps`                          | `100`                         | Maximum number of actions Northstar can take      |
| `temperature`                        | `0.2`                         | Model temperature (higher = more creative)        |
| `screenshot_mode`                    | `"url"`                       | `"url"` or `"base64"` for screenshot delivery     |
| `viewport_width` / `viewport_height` | `1280` / `720`                | Display dimensions in pixels                      |
| `persistent`                         | `false`                       | Save environment state after task completes       |
| `environment_id`                     | —                             | Restore a previous environment’s state            |

For complex tasks, set a higher `max_steps` to give Northstar more room to work. For simple tasks, a lower value keeps things fast and focused.

## See also

- [**Run a task**](/guides/run-a-task/index.md) — streaming, polling, steering, and writing good instructions
- [**Legacy software**](/use-cases/legacy-software/index.md) — Northstar operates enterprise software through the GUI
- [**Cross-app workflows**](/use-cases/cross-app-workflows/index.md) — Northstar moves data between applications
- [**Responses API**](/guides/responses-api/index.md) — build your own loop for full control over every step