​
Overview

At its core, Skylight hosts stable, cloud-based Windows desktop virtual machines, serving as the infrastructure for deploying agents at scale. Each Skylight instance is a fully functional Windows desktop, preloaded with essential software and ready for agent interaction. These instances can be controlled programmatically or used with built-in or custom agents to perform automated tasks. By default, instances come pre-configured with Microsoft Word, Excel, PowerPoint, VS Code, Firefox, and Paint. You can also install additional apps. This guide walks you through managing your instances — starting, pausing, and terminating them as needed.

​
Start a Windows Instance

import os
from skylight_sdk import Skylight

with Skylight(
  apikey=os.getenv("SKYLIGHT_APIKEY", ""),
) as skylight:
  instance = skylight.windows.start()
The start endpoint returns a JSON with these properties:
PropertyDescriptionExample
instance_idUnique identifier of the created instance"i-123456"
messageHuman-readable status message"Instance ready to use"
livestream_urlURL to livestream the instance"launchskylight.com/embed/i-123456"
stateState of the instance"running", "pending", "hibernated", or "terminated"
When starting an instance, you can specify a timeout period (in minutes) after which the instance will automatically terminate. The default timeout is 60 minutes: 
# Specify timeout in minutes (default: 60)
instance = skylight.windows.start(timeout_minutes=120)

​
Instance State Management

To optimize costs, it is recommended to manage the state of your instances.

​
Check instance state

Instances can be running, pending, hibernated, or terminated:
  • Running: you can interact with the instance and operate it with the AI agent
  • Pending: the instance is starting up
  • Hibernated: this preserves the state without incurring full runtime costs. Hibernated instances maintain knowledge, files, and the desktop state.
  • Terminated: the instance is shut down and cannot be recovered. All information (including knowledge, files, and desktop state) is wiped, so make sure to save any important data before terminating.
You can retrieve the current state of your Windows instance: 
state = skylight.windows.state(instance_id="<id>")
The state endpoint returns a JSON with these properties:
PropertyDescriptionExample
instance_idUnique identifier of the instance"i-123456"
stateCurrent state of the instance"running", "pending", "hibernated", or "terminated"
timeoutTimeout in minutes before instance auto-termination60
used_minutesMinutes used by the instance so far10
knowledgeCurrent knowledge of the instance"unknown"
livestream_urlURL to livestream the instance"launchskylight.com/embed/i-123456"
assigned_atWhen the instance was assigned"2023-01-01T12:00:00Z" or null

​
Pause an instance

Hibernate your instance to save its state: 
response = skylight.windows.pause(instance_id="<id>")
The pause endpoint returns a JSON with these properties:
PropertyDescriptionExample
statusStatus of the operation"success"
messageHuman-readable status message"Operation completed successfully"
stateState of the instance"hibernated"
Note: Paused instances are charged one tenth of the price of a running instance per minute.

​
Resume an instance

Resume a previously paused instance: 
response = skylight.windows.resume(instance_id="<id>")
The resume endpoint returns a JSON with these properties:
PropertyDescriptionExample
statusStatus of the operation"success"
messageHuman-readable status message"Operation completed successfully"
stateState of the instance"running"
livestream_urlURL to livestream the instance"launchskylight.com/embed/i-123456"

​
Terminate an instance

Completely shut down and remove an instance: 
response = skylight.windows.terminate(instance_id="<id>")
The terminate endpoint returns a JSON with these properties:
PropertyDescriptionExample
statusStatus of the operation"success"
messageHuman-readable status message"Operation completed successfully"
stateState of the instance"terminated"
Warning: Termination is irreversible and all unsaved data (including knowledge, files, and desktop state) will be lost.

​
List all instances

Get a list of all your Windows instances: 
instances = skylight.windows.instances()
The instances endpoint returns a list of instances with these properties:
PropertyDescriptionExample
instancesArray of instance objects[{...}]
instances[].instance_idUnique identifier of the instance"i-123456"
instances[].stateCurrent state of the instance"running"
instances[].timeoutTimeout in minutes before auto-termination60
instances[].used_minutesMinutes used by the instance so far10
instances[].knowledgeCurrent knowledge of the instance"unknown"
instances[].livestream_urlURL to livestream the instance"launchskylight.com/embed/i-123456"
instances[].assigned_atWhen the instance was assigned (ISO timestamp)"2023-01-01T12:00:00Z"

​
Knowledge

Instances gain knowledge from agent runs over time. Knowledge gives agents context of what previous agents have done to avoid task repetition or ‘forgetting’ of information. When an agent completes a task, it produces a summary of its actions and the final result. Information in the summary is automatically stored in the knowledge of the specific instance to provide context to the agent for future tasks. You can also edit knowledge yourself to give the agent any other context it may need to complete its task. Currently, you can only edit knowledge through the Playground UI.

​
Best Practices

  1. Use timeouts to prevent unintended billing - set an appropriate timeout when starting an instance
  2. Pause VMs when not in use to reduce costs while preserving state
  3. Check VM state before performing operations to ensure it’s in the expected state
  4. Save important data before terminating - download your files and save any other important information before terminating instances

​
Instance Resources

By default, Windows instances are provisioned with standard CPU and RAM configurations. If you need additional resources such as:
  • More RAM
  • Additional CPU cores
  • GPU acceleration
Contact us to upgrade your instance resources.

​
Pricing

Standard Skylight Windows virtual instances are billed at $0.005 a minute. Paused instances are not billed for compute time but incur storage charges of $0.0005 a minute for the preserved state.