Koyeb python sdk

This is the official Python SDK for Koyeb, a platform that allows you to deploy and manage applications and services in the cloud.

Modules

• koyeb.api: Contains the synchronous API client and methods to interact with Koyeb's REST API. Documentation
• koyeb.api_async: Contains the asynchronous API client (httpx-based) and methods to interact with Koyeb's REST API. Documentation
• koyeb.sandbox: Contains the Sandbox module. Documentation

Koyeb Sanboxes

A Koyeb sandbox is an isolated, ephemeral environment designed to safely run, test, and experiment with code without affecting other systems or requiring complex setup. It provides developers with a virtualized or containerized execution space where dependencies, environment variables, and runtime contexts can be fully controlled and discarded after use.

You should use a sandbox to:

• Execute untrusted or user-generated code securely
• Prototype applications quickly
• Test APIs or libraries in clean environments
• Demonstrate functionality without configuring local infrastructure

Sandboxes are especially valuable in platforms for AI model evaluation, online coding environments, CI/CD pipelines, and educational tools that require safe, reproducible, and on-demand compute environments.

Install the SDK

pip install koyeb-sdk

Set the Koyeb API token

Using the Koyeb Python SDK requires an API token. Complete the following steps to generate the token and make it accessible to your environment:

1. In the Koyeb control panel, navigate to Settings.
2. Click the API tab.
3. Click Create API token and provide a name and description. You can use the following: Name:

   sandbox-quickstart
   

   Description:

   For accessing the Koyeb Python SDK to generate sandboxes
   

4. Click Create to complete token creation. Note that the token value will not be accessible later, so take note of it as needed.
5. In the terminal, set the API token to be accessible to your Python environment, replacing the placeholder with your API token:

   export KOYEB_API_TOKEN="YOUR_API_TOKEN"
   

Optionally, set a default region for all sandbox deployments (defaults to "na" if not set):

export KOYEB_REGION="fra"

Example sandbox code

See the examples directory for more basic operations.

Create a file called main.py and add the following application code:

import os
from koyeb import Sandbox

sandbox = Sandbox.create(
    image="ubuntu",
    name="file-ops",
    wait_ready=True,
)

fs = sandbox.filesystem

# Write Python script
python_code = "#!/usr/bin/env python3\nprint('Hello from Python!')\n"
fs.write_file("/tmp/script.py", python_code)
sandbox.exec("chmod +x /tmp/script.py")
result = sandbox.exec("/tmp/script.py")
print(result.stdout.strip())

sandbox.delete()

This code does the following:

• Creates a new sandbox environment using an image of Ubuntu.
• Creates a new Python file in the sandbox at tmp/script.py and adds a "Hello from Python" message to the file.
• Sets the file as executable using chmod +x.
• Executes the Python file.
• Prints the result using stdout.
• Deletes the sandbox.

Run the code

Use the following command to run your code:

python main.py

Your environment spins up in seconds! Then in terminal logs, you'll see the 'Hello from Python!' response.

You can also follow along in the Sandboxes tab of the Koyeb control panel to see as your sandbox environment is set up and then removed.

With Koyeb Sandboxes, you can manage fully flexible sandbox environments at scale using the Koyeb Python SDK.

The Koyeb Sandbox Python module

The Koyeb Sandbox Python module contains functionality to take any actions needed on your sanboxes, including creating and deleting sanboxes, file manipulation, running commands, managing port exposure, and more.

View the reference for the Sandbox module

View Sandboxes documentation on the Koyeb website