Tasks

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. For direct computer control without a model, see the Computers API.

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 — streaming, polling, steering, and writing good instructions
• Legacy software — Northstar operates enterprise software through the GUI
• Cross-app workflows — Northstar moves data between applications
• Responses API — build your own loop for full control over every step