Skip to main content

Quickstart

Install one client to use both el commands and envloop.Client. You need Python 3.11+, Git, and uv. The following installs from source without assuming a PyPI release is available; access to the EnvLoop repository is required.

1. Install​

git clone https://github.com/EnvLoop/envloop.git
cd envloop
uv venv
uv pip install --python .venv/bin/python -e .
uv run --no-sync el --help

Run subsequent commands in this directory. --no-sync preserves manually installed dependencies; you can also activate .venv and run el and python directly.

2. Connect​

Sign in to the platform, create a key under API Keys → Create API Key, and store it securely. Your account must be provisioned and belong to an authorized workspace; see Authentication.

export ENVLOOP_BASE_URL=https://api.envloop.ai
export ENVLOOP_API_KEY='YOUR_ENVLOOP_API_KEY'

Replace the placeholder with your own Key. Do not commit real Keys to Git. If workspace is omitted, the platform selects a default authorized workspace.

3. Submit a dataset job​

uv run --no-sync el job submit --dataset envloop/terminal-bench-2-1-lite

The JSON response includes job_id. Replace JOB_ID below with the returned value:

uv run --no-sync el job status JOB_ID
uv run --no-sync el job result JOB_ID

The dataset must be available on the target platform. When version, config, and split are omitted, the platform resolves and freezes the default selection. The platform continues running the job after the HTTP submission returns; result does not automatically wait. You can wait using submit --wait. Stop with el job stop JOB_ID.

4. Submit your own task​

Create a directory containing only these two files:

mkdir -p my-task
cat > my-task/runner.toml <<'TOML'
schema_version = "envhub.runner/v1"
[runner]
name = "examples/hello"
version = "1"
[execution]
entrypoint = "main.py"
timeout_sec = 10
outputs = ["result.txt"]
TOML
cat > my-task/main.py <<'PY'
from pathlib import Path

Path("result.txt").write_text("hello\n", encoding="utf-8")
print("hello")
PY
uv run --no-sync el task submit ./my-task --wait

After obtaining trial_id, run uv run --no-sync el task result TRIAL_ID to inspect stdout, stderr, and outputs. The successful terminal state is succeeded; Task completion does not mean benchmark reward=1.

5. Use the Python SDK​

Save as quickstart.py and run uv run --no-sync python quickstart.py in the same virtual environment:

from envloop import Client

with Client.remote() as client:
    trial = client.tasks.submit("./my-task")
    final = client.tasks.wait(trial["trial_id"], timeout=60)
    if final["status"] != "succeeded":
        raise RuntimeError(f"Trial ended: {final['status']}")
    result = client.tasks.result(trial["trial_id"])
    print(result["stdout"])
    print(result["outputs"])

The SDK reads system environment variables and does not automatically read .env.local. Without a platform account, install the optional EnvPlatform backend and use the Python SDK local example. Next: Core concepts, Run jobs, and CLI reference.