> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryflavia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instances

> Deploy and manage Windows instances

## 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

<CodeGroup>
  ```python Python theme={null}
  import os
  from skylight_sdk import Skylight

  with Skylight(
    apikey=os.getenv("SKYLIGHT_APIKEY", ""),
  ) as skylight:
    instance = skylight.windows.start()
  ```

  ```typescript TypeScript theme={null}
  import { Skylight } from "skylight-sdk";

  const skylight = new Skylight({
    apikey: process.env["SKYLIGHT_APIKEY"] ?? "",
  });

  async function run() {
    const instance = await skylight.windows.start({});
    console.log(instance);
  }

  run();
  ```
</CodeGroup>

The `start` endpoint returns a JSON with these properties:

| Property         | Description                               | Example                                                     |
| ---------------- | ----------------------------------------- | ----------------------------------------------------------- |
| `instance_id`    | Unique identifier of the created instance | `"i-123456"`                                                |
| `message`        | Human-readable status message             | `"Instance ready to use"`                                   |
| `livestream_url` | URL to livestream the instance            | `"launchskylight.com/embed/i-123456"`                       |
| `state`          | State 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:

<CodeGroup>
  ```python Python theme={null}
  # Specify timeout in minutes (default: 60)
  instance = skylight.windows.start(timeout_minutes=120)
  ```

  ```typescript TypeScript theme={null}
  // Specify timeout in minutes (default: 60)
  const instance = await skylight.windows.start({ timeout_minutes: 120 });
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```python Python theme={null}
  state = skylight.windows.state(instance_id="<id>")
  ```

  ```typescript TypeScript theme={null}
  const state = await skylight.windows.state("<id>");
  ```
</CodeGroup>

The `state` endpoint returns a JSON with these properties:

| Property         | Description                                         | Example                                                     |
| ---------------- | --------------------------------------------------- | ----------------------------------------------------------- |
| `instance_id`    | Unique identifier of the instance                   | `"i-123456"`                                                |
| `state`          | Current state of the instance                       | `"running"`, `"pending"`, `"hibernated"`, or `"terminated"` |
| `timeout`        | Timeout in minutes before instance auto-termination | `60`                                                        |
| `used_minutes`   | Minutes used by the instance so far                 | `10`                                                        |
| `knowledge`      | Current knowledge of the instance                   | `"unknown"`                                                 |
| `livestream_url` | URL to livestream the instance                      | `"launchskylight.com/embed/i-123456"`                       |
| `assigned_at`    | When the instance was assigned                      | `"2023-01-01T12:00:00Z"` or `null`                          |

### Pause an instance

Hibernate your instance to save its state:

<CodeGroup>
  ```python Python theme={null}
  response = skylight.windows.pause(instance_id="<id>")
  ```

  ```typescript TypeScript theme={null}
  const response = await skylight.windows.pause("<id>");
  ```
</CodeGroup>

The `pause` endpoint returns a JSON with these properties:

| Property  | Description                   | Example                              |
| --------- | ----------------------------- | ------------------------------------ |
| `status`  | Status of the operation       | `"success"`                          |
| `message` | Human-readable status message | `"Operation completed successfully"` |
| `state`   | State 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:

<CodeGroup>
  ```python Python theme={null}
  response = skylight.windows.resume(instance_id="<id>")
  ```

  ```typescript TypeScript theme={null}
  const response = await skylight.windows.resume("<id>");
  ```
</CodeGroup>

The `resume` endpoint returns a JSON with these properties:

| Property         | Description                    | Example                               |
| ---------------- | ------------------------------ | ------------------------------------- |
| `status`         | Status of the operation        | `"success"`                           |
| `message`        | Human-readable status message  | `"Operation completed successfully"`  |
| `state`          | State of the instance          | `"running"`                           |
| `livestream_url` | URL to livestream the instance | `"launchskylight.com/embed/i-123456"` |

### Terminate an instance

Completely shut down and remove an instance:

<CodeGroup>
  ```python Python theme={null}
  response = skylight.windows.terminate(instance_id="<id>")
  ```

  ```typescript TypeScript theme={null}
  const response = await skylight.windows.terminate("<id>");
  ```
</CodeGroup>

The `terminate` endpoint returns a JSON with these properties:

| Property  | Description                   | Example                              |
| --------- | ----------------------------- | ------------------------------------ |
| `status`  | Status of the operation       | `"success"`                          |
| `message` | Human-readable status message | `"Operation completed successfully"` |
| `state`   | State 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:

<CodeGroup>
  ```python Python theme={null}
  instances = skylight.windows.instances()
  ```

  ```typescript TypeScript theme={null}
  const instances = await skylight.windows.instances();
  ```
</CodeGroup>

The `instances` endpoint returns a list of instances with these properties:

| Property                     | Description                                    | Example                               |
| ---------------------------- | ---------------------------------------------- | ------------------------------------- |
| `instances`                  | Array of instance objects                      | `[{...}]`                             |
| `instances[].instance_id`    | Unique identifier of the instance              | `"i-123456"`                          |
| `instances[].state`          | Current state of the instance                  | `"running"`                           |
| `instances[].timeout`        | Timeout in minutes before auto-termination     | `60`                                  |
| `instances[].used_minutes`   | Minutes used by the instance so far            | `10`                                  |
| `instances[].knowledge`      | Current knowledge of the instance              | `"unknown"`                           |
| `instances[].livestream_url` | URL to livestream the instance                 | `"launchskylight.com/embed/i-123456"` |
| `instances[].assigned_at`    | When 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.