Add MISTRAL_ environment variable support with precedence over KOYEB_

- Add helper functions (get_api_token, get_api_host, get_region) in utils.py
- Update get_api_clients() and get_async_api_clients() to check MISTRAL_ vars first
- Update sandbox.py and snapshot.py to use the new helper functions
- Update documentation and examples to mention both MISTRAL_ and KOYEB_ env vars
- MISTRAL_API_TOKEN, MISTRAL_API_HOST, and MISTRAL_REGION take precedence over KOYEB_ counterparts

This allows users to use either MISTRAL_ or KOYEB_ environment variables, with
MISTRAL_ variables taking precedence when both are set.

Co-authored-by: nicoche <nicoche@users.noreply.github.com>

Author: mistral-vibe

docs/sandbox.md

@@ -1093,8 +1093,8 @@ Create a new sandbox instance.
   file paths to file contents. Values can be plain strings (default permissions 0644)
   or ``ConfigFile`` instances for custom permissions
   (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")})
-- `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set.
-- `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
+- `region` - Region to deploy to. Defaults to MISTRAL_REGION or MISTRAL_REGION or KOYEB_REGION env var, or "na" if not set.
+- `api_token` - Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
 - `timeout` - Timeout for sandbox creation in seconds
 - `idle_timeout` - Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep:
   - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep=3900)
@@ -1116,7 +1116,7 @@ Create a new sandbox instance.
 - `poll_interval` - Time between health checks in seconds when wait_ready is True (default: 0.5)
 - `entrypoint` - Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"])
 - `command` - Override the default command of the Docker image (e.g., "python app.py")
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 - `block_network` - If True, block all outbound network access from the sandbox
 - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations;
   all other outbound traffic is blocked. Bare IPs are normalized to
@@ -1164,8 +1164,8 @@ Get a sandbox by service ID.
 **Arguments**:
 
 - `id` - Service ID of the sandbox
-- `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+- `api_token` - Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 
 
 **Returns**:
@@ -1623,8 +1623,8 @@ Get a sandbox by service ID asynchronously.
 **Arguments**:
 
 - `id` - Service ID of the sandbox
-- `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+- `api_token` - Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 
 
 **Returns**:
@@ -1690,8 +1690,8 @@ Create a new sandbox instance with async support.
   file paths to file contents. Values can be plain strings (default permissions 0644)
   or ``ConfigFile`` instances for custom permissions
   (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")})
-- `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set.
-- `api_token` - Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
+- `region` - Region to deploy to. Defaults to MISTRAL_REGION or MISTRAL_REGION or KOYEB_REGION env var, or "na" if not set.
+- `api_token` - Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
 - `timeout` - Timeout for sandbox creation in seconds
 - `idle_timeout` - Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep:
   - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep uses _experimental_deep_sleep_value)
@@ -1715,7 +1715,7 @@ Create a new sandbox instance with async support.
 - `poll_interval` - Time between health checks in seconds when wait_ready is True (default: 0.5)
 - `entrypoint` - Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"])
 - `command` - Override the default command of the Docker image (e.g., "python app.py")
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 - `block_network` - If True, block all outbound network access from the sandbox
 - `outbound_allowlist` - List of IPs/CIDRs allowed as outbound destinations;
   all other outbound traffic is blocked. Bare IPs are normalized to
@@ -2001,8 +2001,8 @@ Caches clients by (token, host) to reuse the underlying HTTP connection pool.
 
 **Arguments**:
 
-- `api_token` - Koyeb API token. If not provided, will try to get from KOYEB_API_TOKEN env var
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+- `api_token` - Koyeb API token. If not provided, will try to get from MISTRAL_API_TOKEN or MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 
 
 **Returns**:
@@ -2040,8 +2040,8 @@ Caches clients by (token, host) to reuse the underlying HTTP connection pool.
 
 **Arguments**:
 
-- `api_token` - Koyeb API token. If not provided, will try to get from KOYEB_API_TOKEN env var
-- `host` - Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var
+- `api_token` - Koyeb API token. If not provided, will try to get from MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var
+- `host` - Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or KOYEB_API_HOST env var
 
 
 **Returns**:
@@ -2220,7 +2220,7 @@ Create deployment definition for a sandbox service.
 - `exposed_port_protocol` - Protocol to expose ports with ("http" or "http2").
   If None, defaults to "http".
   If provided, must be one of "http" or "http2".
-- `region` - Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set.
+- `region` - Region to deploy to. Defaults to MISTRAL_REGION or MISTRAL_REGION or KOYEB_REGION env var, or "na" if not set.
 - `routes` - List of routes for public access
 - `idle_timeout` - Number of seconds to wait before sleeping the instance if it receives no traffic
 - `enable_tcp_proxy` - If True, enables TCP proxy for direct TCP access to port 3031

examples/01_create_sandbox.py

@@ -10,9 +10,9 @@
 
 
 def main():
-    api_token = os.getenv("KOYEB_API_TOKEN")
+    api_token = os.getenv("MISTRAL_API_TOKEN") or os.getenv("KOYEB_API_TOKEN")
     if not api_token:
-        print("Error: KOYEB_API_TOKEN not set")
+        print("Error: MISTRAL_API_TOKEN or KOYEB_API_TOKEN not set")
         return 1
 
     sandbox = None

examples/01_create_sandbox_async.py

@@ -12,9 +12,9 @@
 
 
 async def main():
-    api_token = os.getenv("KOYEB_API_TOKEN")
+    api_token = os.getenv("MISTRAL_API_TOKEN") or os.getenv("KOYEB_API_TOKEN")
     if not api_token:
-        print("Error: KOYEB_API_TOKEN not set")
+        print("Error: MISTRAL_API_TOKEN or KOYEB_API_TOKEN not set")
         return 1
 
     sandbox = None

examples/README.md

@@ -5,7 +5,9 @@ A collection of examples demonstrating the Koyeb Sandbox SDK capabilities.
 ## Quick Start
 
 ```bash
-# Set your API token
+# Set your API token (MISTRAL_API_TOKEN takes precedence over KOYEB_API_TOKEN)
+export MISTRAL_API_TOKEN=your_api_token_here
+# or
 export KOYEB_API_TOKEN=your_api_token_here
 
 # Run individual examples

koyeb/sandbox/sandbox.py

@@ -38,6 +38,7 @@
     create_koyeb_sandbox_routes,
     create_sandbox_client,
     get_api_clients,
+    get_api_token,
     logger,
     validate_port,
 )
@@ -165,8 +166,8 @@ def create(
                     file paths to file contents. Values can be plain strings (default permissions 0644)
                     or ``ConfigFile`` instances for custom permissions
                     (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")})
-                region: Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set.
-                api_token: Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
+                region: Region to deploy to. Defaults to MISTRAL_REGION or KOYEB_REGION env var, or "na" if not set.
+                api_token: Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
                 timeout: Timeout for sandbox creation in seconds
                 idle_timeout: Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep:
                     - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep=3900)
@@ -188,7 +189,7 @@ def create(
                 poll_interval: Time between health checks in seconds when wait_ready is True (default: 0.5)
                 entrypoint: Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"])
                 command: Override the default command of the Docker image (e.g., "python app.py")
-                host: Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+                host: Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
                 block_network: If True, block all outbound network access from the sandbox
                 outbound_allowlist: List of IPs/CIDRs allowed as outbound destinations;
                     all other outbound traffic is blocked. Bare IPs are normalized to
@@ -234,10 +235,10 @@ def create(
             ... )
         """
         if api_token is None:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
             if not api_token:
                 raise ValueError(
-                    "API token is required. Set KOYEB_API_TOKEN environment variable or pass api_token parameter"
+                    "API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable or pass api_token parameter"
                 )
 
         # Handle snapshot parameter (can be Snapshot object or snapshot name/ID string)
@@ -502,8 +503,8 @@ def get_from_id(
 
         Args:
             id: Service ID of the sandbox
-            api_token: Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
-            host: Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+            api_token: Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
+            host: Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 
         Returns:
             Sandbox: The Sandbox instance
@@ -513,10 +514,10 @@ def get_from_id(
             SandboxError: If sandbox is not found or retrieval fails
         """
         if api_token is None:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
             if not api_token:
                 raise ValueError(
-                    "API token is required. Set KOYEB_API_TOKEN environment variable or pass api_token parameter"
+                    "API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable or pass api_token parameter"
                 )
 
         if not id:
@@ -1538,8 +1539,8 @@ async def get_from_id(
 
         Args:
             id: Service ID of the sandbox
-            api_token: Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
-            host: Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+            api_token: Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
+            host: Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
 
         Returns:
             AsyncSandbox: The AsyncSandbox instance
@@ -1549,10 +1550,10 @@ async def get_from_id(
             SandboxError: If sandbox is not found or retrieval fails
         """
         if api_token is None:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
             if not api_token:
                 raise ValueError(
-                    "API token is required. Set KOYEB_API_TOKEN environment variable or pass api_token parameter"
+                    "API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable or pass api_token parameter"
                 )
 
         if not id:
@@ -1675,8 +1676,8 @@ async def create(
                     file paths to file contents. Values can be plain strings (default permissions 0644)
                     or ``ConfigFile`` instances for custom permissions
                     (e.g., {"/etc/myapp/config.yaml": "key: value", "/etc/myapp/cert.pem": ConfigFile(content="...", permissions="0600")})
-                region: Region to deploy to. Defaults to KOYEB_REGION env var, or "na" if not set.
-                api_token: Koyeb API token (if None, will try to get from KOYEB_API_TOKEN env var)
+                region: Region to deploy to. Defaults to MISTRAL_REGION or KOYEB_REGION env var, or "na" if not set.
+                api_token: Koyeb API token (if None, will try to get from MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
                 timeout: Timeout for sandbox creation in seconds
                 idle_timeout: Sleep timeout in seconds. Behavior depends on _experimental_enable_light_sleep:
                     - If _experimental_enable_light_sleep is True: sets light_sleep value (deep_sleep uses _experimental_deep_sleep_value)
@@ -1700,7 +1701,7 @@ async def create(
                 poll_interval: Time between health checks in seconds when wait_ready is True (default: 0.5)
                 entrypoint: Override the default entrypoint of the Docker image (e.g., ["/bin/sh", "-c"])
                 command: Override the default command of the Docker image (e.g., "python app.py")
-                host: Koyeb API host URL. If not provided, will try to get from KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
+                host: Koyeb API host URL. If not provided, will try to get from MISTRAL_API_HOST or KOYEB_API_HOST env var (defaults to https://app.koyeb.com)
                 block_network: If True, block all outbound network access from the sandbox
                 outbound_allowlist: List of IPs/CIDRs allowed as outbound destinations;
                     all other outbound traffic is blocked. Bare IPs are normalized to
@@ -1720,10 +1721,10 @@ async def create(
                     or an allowlist entry is not a valid IP address or CIDR
         """
         if api_token is None:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
             if not api_token:
                 raise ValueError(
-                    "API token is required. Set KOYEB_API_TOKEN environment variable or pass api_token parameter"
+                    "API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable or pass api_token parameter"
                 )
 
         # Handle snapshot parameter (can be Snapshot object or snapshot name/ID string)

koyeb/sandbox/snapshot.py

@@ -13,7 +13,7 @@
 from typing import Any, ClassVar, Dict, List, Optional, Union
 
 from .sandbox import Sandbox
-from .utils import SandboxError, get_api_clients
+from .utils import SandboxError, get_api_clients, get_api_token
 
 
 class SnapshotType(Enum):
@@ -77,7 +77,7 @@ def get(
 
         Args:
             snapshot_id: The ID of the snapshot to retrieve
-            api_token: Koyeb API token (falls back to KOYEB_API_TOKEN env var)
+            api_token: Koyeb API token (falls back to MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
             host: Koyeb API host
 
         Returns:
@@ -86,12 +86,10 @@ def get(
         Raises:
             SandboxError: If snapshot cannot be retrieved
         """
-        import os
-
         if not api_token:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
         if not api_token:
-            raise SandboxError("API token is required. Set KOYEB_API_TOKEN environment variable.")
+            raise SandboxError("API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable.")
 
         try:
             clients = get_api_clients(api_token, host)
@@ -128,18 +126,16 @@ def list(
             status: Filter by snapshot status
             limit: Maximum number of snapshots to return
             offset: Offset for pagination
-            api_token: Koyeb API token
+            api_token: Koyeb API token (falls back to MISTRAL_API_TOKEN or KOYEB_API_TOKEN env var)
             host: Koyeb API host
 
         Returns:
             List of Snapshot objects
         """
-        import os
-
         if not api_token:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
         if not api_token:
-            raise SandboxError("API token is required. Set KOYEB_API_TOKEN environment variable.")
+            raise SandboxError("API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable.")
 
         try:
             from koyeb.api.models.instance_snapshot_type import InstanceSnapshotType
@@ -381,12 +377,10 @@ def __init__(
             host: Koyeb API host
             delete_builder: Whether to delete the builder sandbox after creating the snapshot (default: True)
         """
-        import os
-
         if not api_token:
-            api_token = os.getenv("KOYEB_API_TOKEN")
+            api_token = get_api_token()
         if not api_token:
-            raise SandboxError("API token is required. Set KOYEB_API_TOKEN environment variable.")
+            raise SandboxError("API token is required. Set MISTRAL_API_TOKEN or KOYEB_API_TOKEN environment variable.")
 
         self._name = name
         self._image = image