A computer is a whole Windows desktop in its own machine: the screen, the real mouse and keyboard anywhere, and the operating system itself. Start one with the session client, then connect.
from halyard import Client

client = Client()
computer = client.computers.create(viewport={"width": 1920, "height": 1080})
try:
    with computer.connect() as pc:
        print(pc.screen_size)
finally:
    computer.stop()
A computer keeps running until it is stopped. Stop it in finally so it stops even when your code raises.

client.computers.create()

Start a Windows desktop and return once it is ready to drive.
client.computers.create(*, viewport=None, tier=None, telemetry=None)
ParameterTypeDefaultDescription
viewportdict | None1920 x 1080{"width", "height"}: the desktop’s resolution. It must be one of the display modes below.
tierstr | None"standard"Live-view video quality: standard, high or extra_high. Higher tiers cost more per hour.
telemetrybool | NoneTrueFalse turns off the computer’s event stream for its life.
Returns ComputerSession. Raises InvalidArgsError for a viewport that isn’t a display mode. Display modes: 1024x768, 1280x720, 1280x800, 1280x1024, 1366x768, 1440x900, 1536x864, 1600x900, 1680x1050, 1920x1080, 1920x1200, 2560x1440. Change it later with pc.display.set_size().

client.computers.get()

client.computers.get(computer_id)
Returns ComputerSession, including its recording once ready.

client.computers.list()

Your organization’s computers, newest first.
client.computers.list(*, status=None, limit=50)
ParameterTypeDefaultDescription
statusstr | NoneNoneOnly "starting", "active" or "ended" computers.
limitint50How many to return.
Returns list[ComputerSession].

client.computers.stop()

End a computer. Its machine is reset for the next customer.
client.computers.stop(computer_id)

ComputerSession

What create(), get() and list() return.
MemberTypeDescription
idstrThe computer id.
statusstrstarting, active or ended.
control_urlstr | NoneThe DCP WebSocket URL, with a short-lived token. Present on the create() result.
datadictThe full object: viewport, tier, end_reason, recording_status, recording_url and the rest.
connect(*, timeout=60.0)ComputerOpen the control socket. Raises HalyardError when there is no control URL; get a fresh one with create().
refresh()ComputerSessionRe-read it so status and data are current.
stop()NoneEnd the computer.

Computer.connect()

Open a computer’s control socket directly and perform the DCP handshake.
from halyard import Computer

pc = Computer.connect(control_url=None, *, timeout=60.0, client=None)
ParameterTypeDefaultDescription
control_urlstr | NoneHALYARD_CONTROL_URLThe computer’s control URL. Raises ValueError when neither is set.
timeoutfloat60.0Seconds to wait for any one reply.
clientstr | NoneNoneA short lowercase name for an extra connection beside the main one, as on a browser.
Returns Computer. Raises NotConnectedError when the socket can’t open, for any reason: a refused or expired token, an ended computer, or a network failure. The message says which. TimeoutError when the handshake gets no reply within timeout.

What a computer can do

Commands run as the session’s user, who has administrator rights: the machine is yours alone for the session and is reset after it ends.
  • Everything under C:\ax belongs to the session’s own software and is read-only, except C:\ax\downloads.
  • Windows’ own processes and the session’s agent and streamer can’t be ended.
  • A file transfer is at most 32 MiB each way.
  • processes.run() keeps the first 1 MiB of each output stream.
  • Every timeout on a computer is in milliseconds.