Computers

A computer is an isolated cloud environment that Northstar operates in (via Tasks or the Responses API), or that you control directly with the Computers API. Each one runs Lightcone OS — a minimal desktop runtime optimized for Northstar.

When you use Tasks, the computer is created and managed for you automatically. You only need this page if you’re building your own computer-use loop or doing direct programmatic control.

Desktop vs. browser

	Desktop	Browser
kind	"desktop"	"browser"
Environment	Full Lightcone OS desktop	Lightcone OS with Chromium in foreground
Use cases	Native apps, multi-app workflows, OS-level work	Web automation, scraping, testing
Tab management	No	Yes
Proxy support	No	Yes (stealth mode, residential proxies)
File system	Full Linux filesystem	Isolated per session

Lifecycle

Create

from tzafon import Lightcone

client = Lightcone()

# High-level wrapper with automatic cleanup
with client.computer.create(kind="desktop") as computer:
    result = computer.screenshot()
    print(computer.get_screenshot_url(result))
    # computer terminates when block exits

import Lightcone from "@tzafon/lightcone";

const client = new Lightcone();
const computer = await client.computers.create({ kind: "desktop" });

const result = await client.computers.screenshot(computer.id!);
console.log(result.result?.screenshot_url);

// Always clean up when done
await client.computers.delete(computer.id!);

Interact

Every action returns an ActionResult containing a status, optional result data, and optional page_context with viewport state.

computer.click(100, 200)
computer.type("hello world")
computer.hotkey("enter")
computer.scroll(0, 300, 640, 400)  # dx, dy, x, y

result = computer.screenshot()
url = computer.get_screenshot_url(result)

html_result = computer.html()
content = computer.get_html_content(html_result)

const id = computer.id!;

await client.computers.click(id, { x: 100, y: 200 });
await client.computers.type(id, { text: "hello world" });
await client.computers.hotkey(id, { keys: ["Enter"] });
await client.computers.scroll(id, { dx: 0, dy: 300, x: 640, y: 400 });

const result = await client.computers.screenshot(id);
const url = result.result?.screenshot_url as string;

const htmlResult = await client.computers.html(id);
const content = htmlResult.result?.html_content as string;

Action	Result key	Value
screenshot()	screenshot_url	URL of the captured screenshot
html()	html_content	The page’s HTML as a string
debug()	debug_response	Shell command output

Terminate

# Automatic with context manager (recommended)
with client.computer.create(kind="desktop") as computer:
    pass  # ... work with the computer

# Or manual cleanup
computer = client.computers.create(kind="desktop")
result = client.computers.screenshot(computer.id)
client.computers.delete(computer.id)

await client.computers.delete(computer.id!);

ComputerSession (high-level wrapper)

Both SDKs provide a ComputerSession class that binds a computer ID to convenience methods, so you don’t have to pass the ID on every call.

Python — accessed via client.computer.create() with a context manager:

with client.computer.create(kind="desktop") as computer:
    computer.click(100, 200)
    computer.type("hello")
    result = computer.screenshot()
    url = computer.get_screenshot_url(result)

TypeScript — imported from the package and created with ComputerSession.create():

import Lightcone, { ComputerSession } from "@tzafon/lightcone";

const client = new Lightcone();
const computer = await ComputerSession.create(client, { kind: "desktop" });

try {
  await computer.click(100, 200);
  await computer.type("hello");
  const result = await computer.screenshot();
  const url = ComputerSession.getScreenshotUrl(result);
} finally {
  await computer.terminate();
}

The examples in these docs use the lower-level client.computers resource for explicitness, but ComputerSession is the recommended approach for most use cases.

Actions reference

Mouse

Action	Description
click(x, y)	Left-click at pixel coordinates
double_click(x, y)	Double-click
right_click(x, y)	Right-click (context menu)
drag(x1, y1, x2, y2)	Click-and-drag between two points
mouse_down(x, y)	Press and hold the mouse button
mouse_up(x, y)	Release the mouse button

Keyboard

Action	Description
type(text)	Type text into the focused element
hotkey(keys)	Press a key combination (e.g., ["Control", "c"])
key_down(key)	Press and hold a key
key_up(key)	Release a held key

Navigation & viewport

Action	Description
navigate(url)	Go to a URL (browser mode)
scroll(dx, dy, x, y)	Scroll at position by delta
viewport(width, height)	Resize the viewport
screenshot()	Capture the current screen
html()	Get the page HTML (browser mode)

Coordinates are screenshot pixel positions. If you see a button at pixel (500, 300) in a screenshot, send x=500, y=300.

Timeouts and keepalive

Parameter	Default	Description
timeout_seconds	Plan-dependent	Maximum total lifetime
inactivity_timeout_seconds	Plan-dependent	Time with no API calls before auto-termination
auto_kill	true	Whether the inactivity timeout is active

computer.keep_alive()

await client.computers.keepalive(computer.id!);

Persistent state

Save environment state and restore it later:

# Save state on termination
with client.computer.create(kind="desktop", persistent=True) as computer:
    result = computer.screenshot()
    # State saved automatically when terminated

# Restore later
with client.computer.create(
    kind="desktop",
    environment_id="previous_computer_id",
    persistent=True,
) as computer:
    result = computer.screenshot()  # Everything is still there

const computer = await client.computers.create({
  kind: "desktop",
  persistent: true,
});
await client.computers.delete(computer.id!);

const restored = await client.computers.create({
  kind: "desktop",
  environment_id: computer.id!,
  persistent: true,
});

Batch actions

Execute multiple actions in a single request:

results = client.computers.batch(computer.id, actions=[
    {"type": "click", "x": 100, "y": 200},
    {"type": "type", "text": "search query"},
    {"type": "hotkey", "keys": ["Enter"]},
    {"type": "screenshot"},
])

const results = await client.computers.batch(computer.id!, {
  actions: [
    { type: "click", x: 100, y: 200 },
    { type: "type", text: "search query" },
    { type: "hotkey", keys: ["Enter"] },
    { type: "screenshot" },
  ],
});

Proxy support (browser mode)

with client.computer.create(kind="browser", use_advanced_proxy=True) as computer:
    computer.navigate("https://protected-site.com")

const computer = await client.computers.create({
  kind: "browser",
  use_advanced_proxy: true,
});

Many websites actively block automation. Always check a site’s robots.txt and terms of service before automating.

See also

• Lightcone OS — the desktop runtime environments run on
• Operate a computer — step-by-step walkthrough
• Browser tabs — multi-tab workflows (browser mode)
• Shell commands — run terminal commands
• Troubleshooting — common issues and solutions