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

# Create VM Instance

> Creates or retrieves a VM instance for a specific profile and room. Handles instance provisioning and warm pool claiming.

Creates or retrieves a VM instance for a specific profile and room. This endpoint handles instance provisioning from warm pools or creates new instances as needed.

## Use Cases

* **AI Agent Sessions**: Create isolated environments for different AI agent conversations
* **Development Environments**: Spin up temporary development environments with specific tool configurations
* **Testing Environments**: Create reproducible testing environments for code execution

## Instance Lifecycle

When you create an instance, it progresses through several states:

1. `active` - Instance record created
2. `network_allocated` - IP address assigned
3. `ftap_created` - Network interface configured
4. `image_generated` - VM filesystem prepared
5. `vm_started` - Firecracker VM launched
6. `vm_booted` - VM fully operational
7. `ready` - Instance ready for commands

## Response Examples

### Successful Instance Creation

```json theme={null}
{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", 
  "room_id": "ai-session-123",
  "status": "ready",
  "host": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "host-us-east-1a"
  },
  "profile": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "python-data-science"
  }
}
```

### Service Unavailable (No Hosts Available)

```json theme={null}
{
  "error": "service_unavailable",
  "message": "No available hosts for instance provisioning"
}
```

### Service Unavailable (Instance Not Ready)

```json theme={null}
{
  "error": "instance_not_ready", 
  "message": "Instance is still provisioning, current status: vm_started"
}
```

## Best Practices

* **Room Naming**: Use descriptive room IDs that help identify the session or user context
* **Error Handling**: Always check the response status and handle 503 errors by retrying after a short delay
* **Instance Reuse**: The same profile/room combination will return the same instance if it already exists
* **Cleanup**: Instances are automatically cleaned up after periods of inactivity


## OpenAPI

````yaml POST /api/profile/{profile_id}/room/{room_id}
openapi: 3.1.0
info:
  title: Gentility AI API
  description: >-
    API for instant development environments and AI agent tools. Spin up
    isolated virtual machines, execute commands, access files, and more.
  license:
    name: Proprietary
  version: 1.0.0
  contact:
    name: Gentility AI Support
    url: https://gentility.ai
    email: support@gentility.ai
servers:
  - url: https://api.gentility.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: VM Management
    description: Operations for creating and managing VM instances
  - name: Command Execution
    description: Execute shell commands within VM instances
  - name: File Operations
    description: Read and access files within VM instances
  - name: AI Tools
    description: Tool schemas and capabilities for AI agents
  - name: Profile Management
    description: VM configuration templates and settings
paths:
  /api/profile/{profile_id}/room/{room_id}:
    post:
      tags:
        - VM Management
      summary: Create or retrieve VM instance
      description: >-
        Creates or retrieves a VM instance for a specific profile and room.
        Handles instance provisioning and warm pool claiming.
      parameters:
        - name: profile_id
          in: path
          required: true
          description: UUID of the profile (VM configuration template)
          schema:
            type: string
            format: uuid
        - name: room_id
          in: path
          required: true
          description: Room identifier for instance isolation
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                host_id:
                  type: string
                  format: uuid
                  description: Optional specific host ID to provision on
      responses:
        '200':
          description: Instance created or retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '503':
          description: Service unavailable - no hosts available or instance not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Instance:
      type: object
      required:
        - instance_id
        - profile_id
        - room_id
        - status
      properties:
        instance_id:
          type: string
          format: uuid
          description: Unique identifier for the VM instance
        profile_id:
          type: string
          format: uuid
          description: Profile UUID used for this instance
        room_id:
          type: string
          description: Room identifier for this instance
        status:
          type: string
          enum:
            - active
            - network_allocated
            - ftap_created
            - image_generated
            - vm_started
            - vm_booted
            - ready
          description: Current instance state
        host:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        profile:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code or type
        message:
          type: string
          description: Human-readable error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key authentication using Bearer token format: ''Bearer rk_live_<key>'''

````