Using the Claude Agent SDK with Koyeb Sandboxes for Secure Code Execution

The Claude Agent SDK makes it easy to build autonomous agents that can write files, run commands, and maintain conversational state. These agents can iteratively improve and correct their own work as they operate, often running as long-lived processes that maintain and evolve their internal state over time.

But giving an AI agent the ability to execute code also means it can end up doing things you did not intend. It might run commands you did not ask for, read or write files outside its scope, consume more resources than expected, or interfere with other workloads on the machine it's running on. These are the typical risks associated with running untrusted code directly on a host machine.

To keep your infrastructure safe, agents need to run inside fast, fully isolated, sandboxed execution environments that isolate their filesystem, network, processes, and resource usage from the rest of your environment.

In this guide, we will show how to use the Claude Agent SDK with Koyeb Sandboxes, which provide fast, scalable, fully isolated environments for safely executing AI-generated code by building a minimal autonomous agent running inside a Koyeb Sandbox.

Requirements

To successfully follow and complete this guide, you need:

A Koyeb account to create Sandboxes
A Koyeb API key to create and manage Sandboxes
A Claude API key from Anthropic to use the Claude Agent SDK
Python 3.10+ installed on your machine
uv installed on your machine to manage Python dependencies

Steps

To complete this guide and build a minimalistic AI agent running inside a Koyeb Sandbox, you'll need to follow these steps:

Create a new project
Install project dependencies
Create the Script to execute code in a Koyeb Sandbox
Set up local environment variables
Deploy a Koyeb Sandbox and run the Claude Agent SDK powered agent

Create a new project

To get started, on your local machine, open a terminal and navigate to a location of your choice to create a new project directory:

mkdir claude-agent-sdk-with-koyeb-sandboxes
cd claude-agent-sdk-with-koyeb-sandboxes

Inside the project directory, create a new Python project by running the following command:

uv init

This initializes a new Python project and creates the main.py and pyproject.toml files.

With the environment ready, we can now move on to the next step and install the required dependencies.

Install dependencies

To begin interacting with Koyeb Sandboxes, install the Koyeb Python SDK.

uv add koyeb-python-sdk

This adds the Koyeb Python SDK to the project dependencies which will be used to create and manage Koyeb Sandboxes.

Create the Script to execute code in a Koyeb Sandbox

In the project directory, open the main.py file and replace the content with the following code:

# main.py
import os

from koyeb import Sandbox

sandbox = Sandbox.create(
    image="python:3.12-slim",
    instance_type="small",
    wait_ready=True,
    env={
        "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
    },
)


sandbox.exec(
    "pip install claude-agent-sdk",
    timeout=300,
)


content = """
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are an expert Python developer",
        permission_mode='bypassPermissions',
        cwd="/workspace"
    )

    async for message in query(
        prompt="Create a simple Python script that writes 'Hello, world!' to a file /workspace/hello-world.txt and execute it without asking",
        options=options
    ):
        print(message)

asyncio.run(main())
"""

fs = sandbox.filesystem

fs.mkdir("/workspace")
fs.write_file("/workspace/agent.py", content)

# Create a non-root user to bypass the `--dangerously-skip-permissions` restriction
sandbox.exec("useradd -m agent && chown -R agent:agent /workspace")

sandbox.exec(
    "su agent -c 'python /workspace/agent.py'",
    timeout=300,
)


print(fs.read_file("/workspace/hello-world.txt").content)

sandbox.delete()

What the script does

Creates a new Koyeb sandbox using the python:3.12-slim as the base image on a small instance type (1 vCPU, 1GB RAM)
Installs the Claude Agent SDK
Copies a simple Claude Agent SDK script to the sandbox filesystem at /workspace/agent.py, which creates and executes a Python script that writes 'Hello, world!' to /workspace/hello-world.txt
Executes the python /workspace/agent.py command to run the agent
Reads the content of the /workspace/hello-world.txt resulting from the execution of the Python script performed by the agent

Set up local environment variables

Before running the script, set the following local environment variables:

The Koyeb API key is used to create and manage Sandboxes
The Claude API key is used to use the Claude Agent SDK

In your terminal, run the following command to set the environment variables:

export KOYEB_API_KEY=<YOUR_KOYEB_API_KEY>
export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>

Replace <YOUR_KOYEB_API_KEY> and <YOUR_ANTHROPIC_API_KEY> with your actual Koyeb API key and Claude API key respectively.

Deploy a Koyeb Sandbox and run the Claude Agent SDK powered agent

With everything ready, we can now execute the script to deploy a Koyeb Sandbox and run the Claude Agent SDK powered agent.

In your terminal, run the following command to execute the script:

uv run main.py

The script outputs the content of the /workspace/hello-world.txt file resulting from the execution of the Python script performed by the agent.

Upon execution, the following output is produced:

Hello, world!

After the execution completes, the script automatically deletes the sandbox. You can also delete sandboxes manually from the Koyeb control panel.

Conclusion

In this guide, we showed how to use the Claude Agent SDK with Koyeb Sandboxes to build a minimalistic AI agent that can execute code in a sandboxed, isolated environment. We demonstrated how to turn natural language queries into Python code and execute it securely, returning results safely in a fully sandboxed environment.

Next steps

To learn more, explore the Koyeb Sandboxes documentation and the Claude Agent SDK documentation.
You can extend this example to build more sophisticated agents that handle complex tasks, interact with external APIs, or process larger datasets—all while maintaining the security and isolation provided by Koyeb Sandboxes.
Check out another tutorial on Koyeb Sandboxes: Generate Code Using OpenAI Codex in a Koyeb Sandbox