Getting Started / Python SDK

Installation

# pip
pip install scaledminds

# uv (recommended)
uv add scaledminds

# Poetry
poetry add scaledminds

Synchronous client

from scaledminds import ScaledMinds

# API key loaded from SCALEDMINDS_API_KEY env var by default
client = ScaledMinds()

sandbox = client.environments.create(
    image="python3.12",
    vcpus=1,
    memory_mb=512,
    timeout_seconds=300,
)

print(sandbox.id)  # env_01jxyz...

Async client

Use AsyncScaledMinds for asyncio-based workloads (FastAPI, LangGraph, CrewAI async, etc.).

import asyncio
from scaledminds import AsyncScaledMinds

async def main():
    client = AsyncScaledMinds()

    sandbox = await client.environments.create(
        image="python3.12",
        vcpus=1,
        memory_mb=512,
        timeout_seconds=300,
    )

    result = await client.environments.exec(
        sandbox.id,
        command="python3 --version",
    )
    print(result.stdout)  # Python 3.12.x

    await client.environments.terminate(sandbox.id)

asyncio.run(main())

Context manager (auto-terminate)

Use the sandbox as a context manager. Terminated automatically on exit — even on exceptions.

# Sync
with client.environments.create(
    image="python3.12", vcpus=1, memory_mb=512, timeout_seconds=60,
) as sandbox:
    result = client.environments.exec(
        sandbox.id, command="echo 'inside sandbox'",
    )
    print(result.stdout)
# sandbox.terminate() called automatically here

# Async
async with client.environments.create(
    image="python3.12", vcpus=1, memory_mb=512, timeout_seconds=60,
) as sandbox:
    result = await client.environments.exec(
        sandbox.id,
        command="python3 -c \"print(1+1)\"",
    )
    print(result.stdout)  # 2

Upload files

with open("script.py", "rb") as f:
    client.environments.upload_file(
        sandbox.id,
        path="/workspace/script.py",
        content=f.read(),
    )

result = client.environments.exec(
    sandbox.id,
    command="python3 /workspace/script.py",
)

Error handling

from scaledminds import ScaledMinds, ScaledMindsError

client = ScaledMinds()

try:
    client.environments.create(image="unknown-image")
except ScaledMindsError as e:
    print(e.code)        # "IMAGE_NOT_FOUND"
    print(e.status_code) # 404

LangChain integration

ScaledMinds sandboxes work as secure Python REPL tools inside LangChain agents.

from scaledminds.integrations.langchain import ScaledMindsRepl
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")
repl = ScaledMindsRepl(image="python3.12", vcpus=2)

agent = initialize_agent(
    tools=[repl],
    llm=llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
)

agent.run("Compute the first 10 Fibonacci numbers in Python")