Prerequisite: Ensure you’ve installed the cloudcode SDK and have configured your API keys as described in the Quickstart.

​
Overview

This guide demonstrates advanced Cloud Code SDK features through real examples from the cloud-coding/examples folder. We’ll walk through key capabilities: Architect Mode, cost tracking, asynchronous tasks, and sandbox management.

​
Architect Mode

Leverage a two-model workflow for cost-efficient, high-quality code changes. See architect.py:

from cloudcode import Local
import os

sdk = Local(
    working_dir=os.getcwd(),
    model="o4-mini",           # Planner model
    editor_model="gpt-4.1",    # Editor model for concrete changes
    architect_mode=True,
    api_key=os.getenv("CLOUD_CODE_API_KEY")
)

result = sdk.code(
    prompt="Make example.py full of complex math functions",
    editable_files=["example.py"],
    readonly_files=[]
)
print(result["diff"])

​
Tracking Costs and Credits

Easily monitor your API usage (excerpt from Architect Example):

cost_history = sdk.get_cost_history()
for entry in cost_history:
    print(f"{entry['timestamp']}: ${entry['cost']['message_cost']:.4f}")

totals = sdk.get_total_cost(include_markup=True)
print(f"Total cost: ${totals['total_cost']:.2f}")

​
Asynchronous Tasks (Headless)

Run long-running tasks without blocking your application (see Headless Mode):

task = sdk.code_headless(
    prompt="Refactor large codebase to modern patterns",
    editable_files=["src/main.py"],
    readonly_files=["src/config.py"]
)
task_id = task["task_id"]

​
Sandbox Management

Work on entire projects securely in a sandbox (inspired by quick-start.py):

from cloudcode import SandboxSDK
import os

sdk = SandboxSDK(
    model="gpt-4.1",  # Main (planner) model
    editor_model="gpt-4.1-nano",  # Editor model for implementing changes
    architect_mode=True,
    api_key=os.getenv("CLOUD_CODE_API_KEY"),
)

# Get information about the sandbox
sandbox_info = sdk.get_sandbox_info()
print(f"Sandbox created: {sandbox_info['sandbox_id']}")
print(f"Sandbox will expire at: {sandbox_info['end_at']}")


kill_result = sdk.kill_sandbox()
print(f"Sandbox termination: {kill_result['message']}")
print(f"Termination success: {kill_result['success']}")