Manage your compute instances, explore available templates, and control the lifecycle of your virtual environments. This guide also explains how the system automatically discovers and connects to your pt-agent instances behind the scenes.

Working with Templates

Before creating a new compute instance, you need to select a template and a valid deployment zone.

1. 1

   List available templates

   First, retrieve the list of all available compute instance templates in your environment. This will provide you with the template_id needed for the next steps.

2. 2

   Check supported zones

   Not all templates are available in every region. Once you have a template_id, check which zones support it to ensure you deploy your instance in the correct location.

Managing Instances

Once you have your template and zone, you can manage the full lifecycle of your compute instances.

Creating an Instance

To provision a new virtual machine, you will need to provide the template_id and the zone. The system will create the instance based on the template's configuration.

Instance Actions

You can perform several actions to manage the state of an existing compute instance. You will need the instance_id to execute these commands.

Agent Discovery Logic (pt-agent)

The platform uses a smart discovery mechanism to automatically find and connect to your pt-agent via the Studio API proxy. You don't need to manually start your agent instances before making requests; the system handles this for you.

When a request is made that requires the pt-agent, the system follows this workflow:

flowchart TD
    A[Incoming Request] --> B{Is agent cached?}
    B -- Yes --> C[Route request via Studio Proxy]
    B -- No --> D[Search for terminated pt-agent instance]
    D --> E{Instance found?}
    E -- No --> F["Error: No agent available (User must create one)"]
    E -- Yes --> G[Send START command to instance]
    G --> H["Poll instance status (up to 4 mins)"]
    H --> I{Status == RUNNING?}
    I -- No --> J[Timeout Error]
    I -- Yes --> K[Retrieve Internal IP & Port]
    K --> L[Cache target server]
    L --> C

Connection Handling and Retries

• Automatic Polling: When the system starts a terminated agent, it polls the instance status every 10 seconds (up to 24 times) until the instance reports as RUNNING and an internal IP address is assigned.

• Connection Failures: If the Studio proxy becomes unreachable or the connection drops, the system automatically clears the cached agent location. On your next request, it will seamlessly re-trigger the discovery process to find or start a healthy agent.