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

# Acquire a local sandbox

> Initializes a specialized Virtual Machine environment (Local Sandbox) that hosts multiple interconnected MCP servers. Optionally specify a benchmark (e.g., 'Toolathlon') to configure the sandbox. IMPORTANT: The benchmark parameter may affect BOTH (1) the initial data environment (e.g., preloaded data or pre-configured state for supported servers) AND (2) the MCP server implementation itself — some servers may be routed to a benchmark-specific MCP server with potentially different tools or behaviors.



## OpenAPI

````yaml post /local-sandbox
openapi: 3.1.0
info:
  title: Klavis AI (https://www.klavis.ai)
  description: Klavis AI - Open Source MCP Integrations for AI Applications
  version: 0.1.0
servers:
  - url: https://api.klavis.ai
    description: US Production server
  - url: https://api.eu.klavis.ai
    description: EU Production server
security: []
paths:
  /local-sandbox:
    post:
      tags:
        - local-sandbox
      summary: Acquire a local sandbox
      description: >-
        Initializes a specialized Virtual Machine environment (Local Sandbox)
        that hosts multiple interconnected MCP servers. Optionally specify a
        benchmark (e.g., 'Toolathlon') to configure the sandbox. IMPORTANT: The
        benchmark parameter may affect BOTH (1) the initial data environment
        (e.g., preloaded data or pre-configured state for supported servers) AND
        (2) the MCP server implementation itself — some servers may be routed to
        a benchmark-specific MCP server with potentially different tools or
        behaviors.
      operationId: acquire_local_sandbox_local_sandbox_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcquireLocalSandboxRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcquireLocalSandboxResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    AcquireLocalSandboxRequest:
      properties:
        server_names:
          anyOf:
            - items:
                $ref: '#/components/schemas/LocalSandboxMCPServer'
              type: array
            - type: string
              const: ALL
          title: Server Names
          description: >-
            List of MCP servers to acquire, or 'ALL' for all available local
            servers
        benchmark:
          anyOf:
            - $ref: '#/components/schemas/BenchmarkEnum'
            - type: 'null'
          description: >-
            Optional benchmark to configure the local sandbox. NOTE: This
            parameter may affect BOTH (1) the initial data environment
            (preloaded data for supported servers) AND (2) the MCP server
            implementation (some servers are routed to a benchmark-specific MCP
            server with potentially different tools or behaviors).
        test_account_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Test Account Email
          description: Specific test account email
        ttl_seconds:
          anyOf:
            - type: integer
              maximum: 86400
              minimum: 60
            - type: 'null'
          title: Ttl Seconds
          description: >-
            TTL in seconds. The local sandbox will be automatically released
            after this duration. Default: 7200 (2 hours). Min: 60 (1 minute).
            Max: 86400 (24 hours). Set to null to disable auto-release.
          default: 7200
      type: object
      required:
        - server_names
      title: AcquireLocalSandboxRequest
    AcquireLocalSandboxResponse:
      properties:
        local_sandbox_id:
          type: string
          title: Local Sandbox Id
          description: Unique identifier for the entire local sandbox environment
        status:
          anyOf:
            - $ref: '#/components/schemas/SandboxStatus'
            - type: 'null'
          description: Overall status of the local sandbox environment
        benchmark:
          anyOf:
            - type: string
            - type: 'null'
          title: Benchmark
          description: Benchmark environment configuration used for the local sandbox
        servers:
          items:
            $ref: '#/components/schemas/LocalSandboxServerItem'
          type: array
          title: Servers
          description: List of interconnected MCP servers running in this sandbox
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Status message
      type: object
      required:
        - local_sandbox_id
        - servers
      title: AcquireLocalSandboxResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LocalSandboxMCPServer:
      type: string
      enum:
        - filesystem
        - git
        - terminal
        - desktop-commander
        - arxiv
        - excel
        - word
        - powerpoint
        - code-executor
        - code-runner
        - pdf-tools
        - google_cloud
        - poste_email_toolathlon
        - canvas
        - localmemory
        - playwright
      title: LocalSandboxMCPServer
      description: |-
        Supported MCP servers for local sandboxing.
        These are typically stateless or local-only servers.
    BenchmarkEnum:
      type: string
      enum:
        - MCP_Atlas
        - Toolathlon
        - MCP_Mark
      title: BenchmarkEnum
      description: Supported benchmarks for sandbox initial environment
    SandboxStatus:
      type: string
      enum:
        - idle
        - occupied
        - error
      title: SandboxStatus
      description: Status of a sandbox instance - matches database enum
    LocalSandboxServerItem:
      properties:
        server_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Name
          description: Name of the MCP server
        id:
          type: string
          title: Id
          description: >-
            Unique identifier for this specific server instance within the
            sandbox
        mcp_server_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Server Url
          description: URL to connect to this specific MCP server instance
        status:
          anyOf:
            - $ref: '#/components/schemas/SandboxStatus'
            - type: 'null'
          description: Current status of this server's sandbox
        benchmark:
          anyOf:
            - type: string
            - type: 'null'
          title: Benchmark
          description: Benchmark environment configuration
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Last update timestamp
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional metadata for the sandbox
        auth_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Auth Data
          description: Authentication data for the sandbox
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: Sandbox tags
      type: object
      required:
        - id
      title: LocalSandboxServerItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      description: Your Klavis AI API key.
      scheme: bearer
      x-fern-bearer:
        name: api_key

````