Create your first gym

A gym gives the model tasks, the actions it can take, and a check that scores its work. This guide builds a gym from the starter project, checks it on your machine and uploads it privately to your organization.

You need Python 3.11 or later, uv and a GFT Studio account. The starter needs no GFT code and no access to a GFT repository.

Download the starter#

Download the gym starter and extract it. It is a complete small gym: a refund desk. The model reads a fictional order and a shop policy, then decides between a refund, store credit and a denial.

Build and check#

Run these commands in the starter folder:

uv build --wheel
uv run python build_manifest.py
uv run python check_gym.py dist/refund_gym-0.1.0-py3-none-any.whl manifest.json

The check serves the wheel the way the Studio sandbox does and plays one episode for each qualification task. Continue when it prints Ready to upload.

To try the gym by hand, start it and open an episode:

uv run uvicorn refund_gym.app:app --port 8000
curl -X POST localhost:8000/reset -H 'content-type: application/json' -d '{"seed": 1}'

Upload the gym#

1. Open Private gyms → Add private gym and choose Upload a package.
2. Select the wheel and manifest.json. The form takes the gym ID, name, description, category and tags from the manifest.
3. Wait for qualification. Expand the gym to see failed checks, or open the inspector. The inspector shows a budget before a session starts.

To publish from a terminal instead, see Publish with the CLI.

Replace the sample logic#

1. Rename the refund_gym folder and update the names in pyproject.toml.
2. In domain.py, set GYM_ID and replace the tasks, the action and observation schemas, the Episode class and the reward profile.
3. Extend self_test() with checks for your scoring: a correct answer scores high, and each shortcut you can think of scores 0.
4. Build the wheel, rebuild the manifest and run the check again.

The contract#

Studio starts your gym in a sandbox and calls these routes on port 8000. Every answer is a JSON object.

These rules are easy to miss:

• /reset receives the exact task from your manifest, with its hidden and snapshot parts. Studio picks the task. Do not choose your own.
• The reward is a number from 0 to 1. On the final step, return metadata.profile_digest equal to reward_profile.digest from /reset. Studio rejects the reward otherwise.
• Never put a key containing the word hidden, or the task's evidence_id, in an observation or in /state.
• Answer a bad action with HTTP 200 and an error in the observation. Any other status ends the episode as a platform failure.
• End the episode yourself, with done set to true, within max_steps actions.
• Keep a finished session until /close. Studio reads /artifacts and /state after the final step.

The manifest#

build_manifest.py shows every field. hub.families holds the catalog category first, then your own tags. hub.listing is the text of your marketplace page: a summary, one example task, the shortcuts you tried against your reward, and model results. Studio shows it as written by you, next to what it measured from the package. Each task needs id, split, family, vertical, template_family, source_lineage, entity_identity, public, hidden with a unique evidence_id, snapshot, digest and public_digest. A training task must not share its digest, public_digest, entity_identity or source_lineage with a benchmark or qualification task.

Put the answer key in hidden. Studio stores it as private evidence and sends it only to your gym. Put what the task needs to start in snapshot. For large instances, such as files, store only generator inputs like a seed and rebuild the instance in /reset, as the starter does.

Limits#

Every observation is added to the model's context, and the person who trains chooses the token budget for an episode. Keep observations short.

Compiled dependencies#

A wheel cannot contain compiled code or list other dependencies. If your gym needs them, package it as a container image:

FROM python:3.12-slim
RUN pip install --no-cache-dir fastapi uvicorn your-native-package
COPY refund_gym /app/refund_gym
WORKDIR /app
USER 65532:65532
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "refund_gym.app:app", "--host", "0.0.0.0", "--port", "8000"]

Build it for linux/amd64. The image serves the same contract under the same sandbox limits: user 65532, read-only files and no network. Push it to a registry and send your GFT contact the reference with its digest, such as registry.example/gym@sha256:…. GFT places the image on the execution worker. Then choose Use a container image in the upload form and submit the same manifest.json. Check the image first with uv run python check_gym.py --url http://localhost:8000 manifest.json.

Use the gym#

When qualification passes, create a separate marketplace release to offer the gym to other teams. A release needs its own gym ID: change GYM_ID, then rebuild the wheel and the manifest.

Already have a running service?#

Your workspace administrator registers an approved REST or gRPC connection. Its URL and credentials stay on the server. The service implements the same contract. Ask your workspace administrator for the approved connection ID, then follow Publish with the CLI to bind that connection to a gym.