How Lightcone Works

Northstar is a vision-language model that operates computers. It takes a screenshot as input, decides the next action (click, type, scroll, navigate), and outputs structured coordinates. Lightcone provides the API to use Northstar and the cloud environments it operates in.

Architecture

┌──────────────────────────────────────────────────────────┐
│                      Your Code                           │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │    Tasks     │  │ Responses API│  │  Computers    │  │
│  │  (managed)   │  │    (CUA)     │  │  (low-level)  │  │
│  └──────┬───────┘  └──────┬───────┘  └───────┬───────┘  │
└─────────┼─────────────────┼──────────────────┼───────────┘
          │                 │                  │
          ▼                 ▼                  ▼
┌──────────────────────────────────────────────────────────┐
│                   Lightcone API                          │
│                  api.tzafon.ai                           │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────────────────────────────────────────┐     │
│  │               Northstar CUA Fast                │     │
│  │   screenshot in → structured action out          │     │
│  └─────────────────────────────────────────────────┘     │
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │   Desktop   │  │   Desktop   │  │   Browser   │ ...  │
│  │ environment │  │ environment │  │ environment │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│                                                          │
│         Isolated containers · Lightcone OS               │
└──────────────────────────────────────────────────────────┘

Three levels of control

Same platform, three ways in. Pick how much of the loop you want to own. The first two run Northstar for you; the third is the environment alone, with no model involved.

1. Tasks: fully managed

You describe what needs to be done. Northstar operates a computer from start to finish: opening apps, navigating, typing, reading the screen, and making decisions.

for event in client.agent.tasks.start_stream(
    instruction="Open LibreOffice Calc, create a budget spreadsheet with categories for rent, food, and transport",
    kind="desktop",
):
    print(event)

Best for: work that’s easy to describe but tedious to script: filling forms, multi-app workflows, research, data collection.

Learn more →

2. Responses API: build your own loop

You build a computer-use loop: Northstar looks at a screenshot, tells you what action to perform, you execute it, and feed back the new screenshot. You control the loop and can inject custom logic between steps.

response = client.responses.create(
    model="tzafon.northstar-cua-fast-1.6",
    input="Open the terminal and check disk usage",
    tools=[{"type": "computer_use", "environment": "desktop"}],
)
# Execute the action, screenshot, send back, repeat

Best for: custom workflows where you need to validate results, branch on conditions, or integrate with other systems between steps.

Learn more →

3. Computers API: direct control (no model)

You send individual actions to a cloud computer: click, type, navigate, screenshot, shell commands. No model involved; you decide what to do at every step.

with client.computer.create(kind="desktop") as computer:
    client.computers.exec.sync(computer.id, command="firefox https://example.com &")
    computer.wait(3)
    computer.click(400, 300)
    computer.type("hello")
    result = computer.screenshot()

Best for: programmatic automation, testing, and any workflow where you know exactly what steps to take.

Learn more →

Models

Model	Purpose	Input	Output
tzafon.northstar-cua-fast-1.6	Our latest computer-use model. Recommended; pin this version in production.	$0.50/M tokens	$1.50/M tokens
tzafon.northstar-cua-fast	Unversioned alias of the previous generation. Prefer the pinned -1.6.	$0.50/M tokens	$1.50/M tokens
tzafon.sm-1	Text model specialized for low-level systems programming.	$0.20/M tokens	$0.30/M tokens

List the models available to your key at any time with client.models.list().

Northstar CUA Fast is optimized for speed and cost ($0.50/M input, $1.50/M output). It recovers from mistakes and generalizes across desktop and browser environments.

In production, always use a pinned version like tzafon.northstar-cua-fast-1.6. Unversioned aliases are upgraded in place, which can change behavior under you. See Running in production.

All models are available through the Responses API and Chat Completions API. The computer_use tool is supported via the Responses API.

Coordinate system

Northstar outputs GUI actions in a normalized 0–999 coordinate grid. (0,0) is the top-left of the screen, (999,999) is the bottom-right. Coordinates always come back in this 0–999 space; your code converts them to pixels using int(coord / 1000 * display_dim) before passing to click() or other methods.

See Coordinates for the full guide, including scaling formulas, visual examples, and which API to use.

OpenAI-compatible API

Already using the OpenAI SDK? Northstar works as a drop-in. Change the base URL and model name:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tzafon.ai/v1",
    api_key="sk_your_api_key_here",
)

response = client.chat.completions.create(
    model="tzafon.northstar-cua-fast-1.6",
    messages=[{"role": "user", "content": "What is reinforcement learning?"}],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.tzafon.ai/v1",
  apiKey: "sk_your_api_key_here",
});

const response = await client.chat.completions.create({
  model: "tzafon.northstar-cua-fast-1.6",
  messages: [{ role: "user", content: "What is reinforcement learning?" }],
});

Streaming, tool calling, and structured outputs are all supported. See Chat Completions for the full reference.

Environments

When Northstar operates a computer, it runs inside an isolated cloud environment powered by Lightcone OS, a minimal desktop runtime built for model operation. You can choose:

• Desktop (kind: "desktop"): full Linux desktop. Northstar can use any native application.
• Browser (kind: "browser"): Chromium in the foreground, with stealth mode and proxy support for web tasks.

Environments are fully isolated from each other, with a separate filesystem, network stack, and display. They spin up in seconds and are destroyed when you’re done.

The mental model: what lives where

The layers, from most durable to most ephemeral, and what each one persists:

Layer	What it is	Lifetime	What persists
Organization	Your account: API keys, credits, plan limits	Permanent	Keys, usage, saved environments
Environment	A saved snapshot of a computer (environment_id)	Until you delete it	Disk state (desktop) or cookies/storage (browser): including logins
Computer	A live VM (computer_id, also called a session)	Until deleted or idle-reaped	Everything on screen and disk: while it’s alive
Task	One instruction given to Northstar, running on a computer	Start → completion (can span follow-up turns)	The event stream (its trace); replay for ~10 minutes after finish, plus the dashboard replay
Turn / step	One screenshot → decision → action cycle inside a task	Seconds	A screenshot + executed event in the stream

The rules that follow from this:

• A task does not save anything by itself. If a task logs into a site and its computer is destroyed afterward, the login is gone. To keep it, run the task on a persistent: true computer and delete the computer to commit the snapshot. See Logins and sessions.
• A computer outlives its task if you pass keep_alive / terminate_on_completion: false. You can send a follow-up task to the same computer_id, or take over manually with the Computers API.
• Your prompt/harness is not stored in the environment. Environments hold machine state; instructions, system prompts, and models are parameters of each task. Version them in your own code like any other config.
• The trace is the task’s event stream. Consume it live via SSE, re-fetch it for ~10 minutes after completion, or watch/replay in the dashboard at lightcone.ai/c/{computer_id}.

Vision or DOM?

Northstar operates from pixels: screenshots in, coordinates out. That’s what makes it work on anything with a screen: native desktop apps, virtual desktops, canvases, PDFs, legacy UIs where no DOM exists or the DOM lies.

You still have full DOM access when you want it: get_html_content returns the page HTML for parsing, and CDP access lets Playwright or Puppeteer drive the same browser with selectors. The practical split:

• Deterministic, high-volume steps you fully control → selectors/CDP or coordinate scripts (fast, cheap, repeatable)
• Steps that vary, break, or need judgment → Northstar (resilient, no maintenance)
• Reading data out → get_html_content when the DOM is honest; verified extraction from the screen when it isn’t

Many production systems combine them: scripted steps for the known path, Northstar for recovery when the screen doesn’t match expectations. See the cookbook.

Glossary

We say	Also known as
Computer	Session, sandbox, VM, box: a live cloud machine you control
Environment	Snapshot, image, saved state: a computer’s saved disk/cookie state you can boot again
Task	Agent run, job: one plain-language instruction executed autonomously by Northstar
Northstar	The model: Tzafon’s computer-use (CUA) vision-language model
Lightcone	The platform: API, SDKs, CLI, and dashboard around Northstar
Trace	Event stream, run history: the step-by-step record of what a task did

Next steps

• Quickstart: get Northstar running a task in 5 minutes
• Tasks: the simplest way to use Northstar
• Responses API: build your own computer-use loop
• Integrations: connect to LangChain, Playwright, and more