Skip to main content

Python SDK

envloop.Client is a synchronous client. Remote mode requires only envloop; local execution also requires EnvPlatform. See Quickstart for installation.

Connect to the platform​

from envloop import Client

with Client.remote() as client:
    print(client.jobs.list(limit=10))

The SDK reads ENVLOOP_BASE_URL, ENVLOOP_API_KEY, and optional ENVLOOP_WORKSPACE_ID; it does not automatically read .env.local. You can also pass the address and workspace explicitly while keeping the Key in the environment:

with Client.remote("https://api.envloop.ai", timeout=30) as client:
    print(client.jobs.list(limit=10))

Here, timeout is the HTTP request deadline, not the task execution deadline or total wait deadline. Client() does not automatically connect to the platform; pass a caller-managed server or use a factory method.

Run locally without a platform account​

Install the optional backend from the envloop repository directory (reuse existing checkouts without overwriting them):

git clone https://github.com/EnvLoop/EnvPlatform.git ../EnvPlatform
uv pip install --python .venv/bin/python -e ../EnvPlatform

Prepare the two-file ./my-task from Quickstart, save the following as local_demo.py, and run uv run --no-sync python local_demo.py:

from envloop import Client

with Client.local(work_dir="./runs") as client:
    trial = client.tasks.submit("./my-task")
    final = client.tasks.wait(trial["trial_id"], timeout=30)
    assert final["status"] == "succeeded", final
    result = client.tasks.result(trial["trial_id"])
    assert result["stdout"] == "hello\n", result
    assert result["outputs"][0]["content"] == "hello\n", result
    print(result)

Local runs execute trusted scripts directly. Closing the context waits for accepted tasks to finish but does not delete outputs or logs. Without a repository binding, clients cannot retrieve historical Trials held in another client's memory.

Wait and inspect failures​

with Client.remote() as client:
    trial = client.tasks.submit("./my-task")
    trial_id = trial["trial_id"]
    try:
        final = client.tasks.wait(trial_id, timeout=60)
    except TimeoutError:
        print(client.tasks.status(trial_id))  # The task may still be running
    else:
        print(final["status"])
        print(client.tasks.result(trial_id))

When a script exits nonzero, wait returns failed; task failure does not automatically raise an exception. Directory reads, input validation, HTTP, and permission errors may raise exceptions; do not log raw requests, keys, or arbitrary server error bodies.

See Python SDK reference for interface signatures.