Remote functions

This tutorial shows you how to run Python functions inside a sandbox using remote functions. You can call sandbox-executed code as if it were a local function instead of constructing shell command strings. It’s for developers who want to invoke compute in a sandbox directly from their Python code and collect typed results.

Choose authentication

These examples run on serverless capacity unless a section specifies CKS. Choose the credential for the account that owns your sandboxes. See Choose and get credentials to obtain a key or token. Run the installation commands in an active Python virtual environment. Save the Python code from your credential tab as sandbox_auth.py beside the Python scripts you run from this page. It stores the authentication choice, not your credential. The examples import AUTH from that file and pass it explicitly to each new sandbox or session.

W&B API key
CoreWeave API access token

Use your Forge API key through the SDK’s W&B authentication strategy:

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Use the token for your CoreWeave organization:

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

For CKS placement, choose the CoreWeave token, enable a runner, and set placement_mode="cks" on sandbox creation or in SandboxDefaults. Creating a session with auth=AUTH also authenticates the sandboxes it owns. Keep the same credential when reconnecting, listing, or cleaning up sandboxes.

Define and call a remote function

Decorate a function with @session.function() to call it inside the sandbox with .remote(). The call returns a reference you resolve with .result():

from sandbox_auth import AUTH
from cwsandbox import Sandbox, SandboxDefaults

with Sandbox.session(SandboxDefaults(
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    @session.function()
    def add(x: int, y: int) -> int:
        return x + y

    result = add.remote(2, 3).result()  # 5

Run functions in parallel with `.map()`

Use .map() to dispatch many invocations at once and collect their results. Independent calls run concurrently instead of one at a time:

@session.function()
def square(x: int) -> int:
    return x * x

refs = square.map([(1,), (2,), (3,)])
results = [r.result() for r in refs]  # [1, 4, 9]

Next steps

You can now invoke Python functions inside a sandbox as if they were local calls, and fan out work in parallel with .map(). For serialization modes, .local() testing, and more, see the Remote functions guide.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Choose authentication

Define and call a remote function

Run functions in parallel with `.map()`

Next steps

​Choose authentication

​Define and call a remote function

​Run functions in parallel with .map()

​Next steps

Choose authentication

Define and call a remote function

Run functions in parallel with `.map()`

Next steps