Run experiments

Run an experiment

On Experiments → New experiment (team members):

• Machine and GPUs: the experiment gets that many GPUs of its own, as CUDA_VISIBLE_DEVICES. With 0 it sees none. When not enough GPUs are free it waits, first come first served, and starts when they are.
• Code: a git repository (https or git@ URL) and an optional branch, tag or commit, checked out fresh for each run, with an access token for a private https repository; or code already on the machine.
• Working directory: inside the repository, or relative to the home directory.
• Command: run with bash; several lines run in order, e.g. pip install -r requirements.txt then python train.py --config agent.yaml.
• Environment variables: API keys and settings (WANDB_API_KEY, HF_TOKEN, ...). Their values are kept by the platform and never shown again; reruns reuse them.

The experiment page shows its status, the commit it runs, how long it has run and its exit code, with the log live from the machine. Stop sends it SIGTERM (then SIGKILL after 15 seconds); Run again starts a copy.

Experiments run detached on the machine: they keep running if you close the page, and if the platform restarts or loses the connection; the platform picks them up again when it can reach the machine.

Reaching the platform from an experiment

Training and evaluation code usually needs the platform itself, for its environments. Every experiment gets:

so the Python SDK works with no setup:

import platform_sdk

env = platform_sdk.connect("cartpole")  # PLATFORM_URL and PLATFORM_TOKEN
obs, info = env.reset(seed=0)

On a connected machine, PLATFORM_URL is http://127.0.0.1:<port> on the machine itself: while experiments run there, the platform keeps an SSH reverse tunnel (ssh -R) from that port back to itself. Nothing is opened to the internet on either side, and the machine never needs to know where the platform is. The port stays the same for the machine, so the URL stays right if the tunnel reconnects. On the platform's own server ("This server") it is the platform's address directly.

Set PLATFORM_URL among the experiment's variables to use another address instead. Remote forwarding must be allowed by the machine's SSH server (AllowTcpForwarding, on by default).

On the machine

Each experiment has its own directory, ~/.simulusion/runs/<id>/:

Write checkpoints and results wherever your code likes; this directory is left in place after the run.

From scripts

The same through the API, with an API token (Team page):

curl -X POST "$PLATFORM_URL/v0/experiments" \
  -H "Authorization: Bearer $PLATFORM_TOKEN" -H "content-type: application/json" \
  -d '{"machine": "h100-1", "gpus": 2,
       "repo": "https://github.com/acme/agents.git", "ref": "main",
       "command": "python train.py --config configs/agent.yaml",
       "env": {"WANDB_API_KEY": "..."}}'
curl "$PLATFORM_URL/v0/experiments/<id>/logs?offset=0" -H "Authorization: Bearer $PLATFORM_TOKEN"
curl -X POST "$PLATFORM_URL/v0/experiments/<id>/stop" -H "Authorization: Bearer $PLATFORM_TOKEN"

/docs on the platform lists every route (machines and experiments).