Launch a Run

Lyceum Cloud accepts three execution types: Python, Docker image, and Docker Compose. Pick the one that matches how your code is packaged.

You have…	Use
A `.py` script and a `requirements.txt`	Python
A container image (public or private)	Docker image
A multi-service stack (`docker-compose.yml`)	Docker Compose

All three submission paths return an execution_id plus a streaming URL. From that point on you read logs, fetch results, and abort through the same set of endpoints, see Runs.

Choosing a hardware profile

Every run targets a hardware profile (e.g. gpu.a100, gpu.h100). You can only launch on profiles your account is authorised for. Three endpoints help you check what’s available:

Endpoint	Returns
`GET /machine-types`	The full catalogue with hourly pricing
`GET /user/quotas/available-hardware`	Just the profiles your account can use
`GET /resources/available-resources`	Detailed hardware specs and pricing

If a profile you need isn’t listed, contact support@lyceum.technology.

Python

Python is the most common entry point. The CLI handles packaging your script, bundling local imports, and installing pip requirements before the code runs. The .lyceum/config.json workspace file lets you persist requirements and import paths so you don’t need to repeat them on every invocation.

CLI
REST API

lyceum python run script.py --machine gpu.a100 --requirements requirements.txt

Flag	Description
`-m`, `--machine`	Hardware profile (`gpu.a100`, `gpu.h100`, …)
`-r`, `--requirements`	Path to a `requirements.txt`
`-f`, `--file-name`	Display name for the run
`--import`	Local imports to bundle
`--use-config` / `--no-config`	Toggle reading `.lyceum/config.json`
`-d`, `--debug`	Enable debug logging

Manage the workspace config (.lyceum/config.json) for shared dependencies and import paths:

lyceum python config init      # create
lyceum python config show      # print current config
lyceum python config refresh   # regenerate

POST /api/v2/external/execution/streaming/start

Body fields include code (the Python source as a string), machine_type, optional requirements, imports, and other execution options. Returns execution_id and stream_url.

Docker image

Use Docker when your environment is already containerised, for example a CUDA image with preinstalled dependencies, or a job that doesn’t fit the Python entrypoint cleanly. The platform pulls the image, runs the command you specify, and streams stdout/stderr back. For private registries, the request supports two credential modes:

Basic auth, username and password for any registry
AWS, access key, secret key, session token, and region for Amazon ECR

CLI
REST API

lyceum docker run python:3.11-slim -c "python -c 'print(1)'" -m gpu.a100

Flag	Default	Description
`-c`, `--command`	—	Command to run inside the container
`-e`, `--env`	—	Environment variable, e.g. `KEY=value` (repeatable)
`-m`, `--machine`	`gpu.a100`	Machine type
`--s3` / `--no-s3`	on	Mount your storage bucket inside the container
`--s3-mount-path`	`/mnt/s3`	Where to mount the bucket inside the container
`--callback`	—	Webhook URL for completion notification
`--registry-creds`	—	Private registry auth as a JSON string (see Private registry credentials)
`--registry-type`	—	Registry credential type (`basic`, `aws`)

By default the bucket is mounted at /mnt/s3 inside the container.

POST /api/v2/external/execution/image/start

Body: docker_image_ref, docker_run_cmd, docker_run_env, machine_type, and docker_registry_credential_type (basic or aws) plus the matching credential fields when needed. For ECR pass aws_access_key_id, aws_secret_access_key, aws_session_token, aws_region. For other registries pass docker_username and docker_password. Set enable_s3_mount: true to mount your storage bucket (path defaults to s3_mount_path: "/mnt/s3").docker_run_env is a single string of newline-separated KEY=VALUE pairs (.env style), for example "DEBUG=true\nTIMEOUT=300". The CLI builds this for you from repeated -e flags.

Private registry credentials

Public images (for example python:3.11-slim from Docker Hub) need no credentials, just leave them out. A private registry requires login details so Lyceum can pull your image. Two modes are supported:

Mode	Use for	Fields
`basic`	Docker Hub (private), GHCR, GitLab, self-hosted, any username/password registry	username, password
`aws`	Amazon ECR	access key, secret key, session token, region

--registry-creds and --registry-type must always be passed together. A Kubernetes-style .dockerconfigjson is not supported; use the JSON shapes below.

CLI
REST API

The --registry-creds value is a JSON string whose keys depend on --registry-type:

# Basic auth (any username/password registry)
lyceum docker run myregistry.io/team/app:tag -m gpu.a100 \
  --registry-type basic \
  --registry-creds '{"username": "me", "password": "••••••"}'

# AWS ECR
lyceum docker run 123456.dkr.ecr.eu-central-1.amazonaws.com/app:latest -m gpu.a100 \
  --registry-type aws \
  --registry-creds '{"aws_access_key_id": "AKIA…", "aws_secret_access_key": "••••", "aws_session_token": "••••", "region": "eu-central-1"}'

Type	Required JSON keys
`basic`	`username`, `password`
`aws`	`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`, `region` (defaults to `us-east-1`)

In the request body the fields are flat, not nested in a JSON string. Set docker_registry_credential_type, then the matching fields:

// Basic auth
{
  "docker_image_ref": "myregistry.io/team/app:tag",
  "docker_registry_credential_type": "basic",
  "docker_username": "me",
  "docker_password": "••••••"
}

// AWS ECR
{
  "docker_image_ref": "123456.dkr.ecr.eu-central-1.amazonaws.com/app:latest",
  "docker_registry_credential_type": "aws",
  "aws_access_key_id": "AKIA…",
  "aws_secret_access_key": "••••",
  "aws_session_token": "••••",
  "aws_region": "eu-central-1"
}

The region key differs by interface: the CLI JSON uses region, the REST body uses aws_region.

Docker Compose

For multi-service stacks (e.g. an app talking to a database) you can submit a whole docker-compose.yml. The platform brings up all services on the same machine and tears them down when the entrypoint service exits.

CLI
REST API

lyceum compose run docker-compose.yml --machine gpu.a100

Flag	Description
`-m`, `--machine`	Hardware profile
`--env-file`	Env file passed to the stack

POST /api/v2/external/execution/compose/start

Body: the compose_file_code as a string and a machine_type.

Aborting

Each execution type has its own abort endpoint. Use abort to immediately kill a run; for graceful stop (notebooks, interactive sessions), use POST /workloads/stop/{execution_id} instead.

POST /execution/streaming/abort/{execution_id}
POST /execution/image/abort/{execution_id}
POST /execution/compose/abort/{execution_id}

Worked examples

Real CLI and curl invocations for Python and Docker runs.

Runs

Monitor, log, and abort executions after they’re submitted.

Getting Started

Serverless

Instances

Inference

Coding Agents

Workloads

Observability

Tools

Configuration

Account

Choosing a hardware profile

Python

Docker image

Private registry credentials

Docker Compose

Aborting

See also

Worked examples

Runs

​Choosing a hardware profile

​Python

​Docker image

​Private registry credentials

​Docker Compose

​Aborting

​See also

Worked examples

Runs

Choosing a hardware profile

Python

Docker image

Private registry credentials

Docker Compose

Aborting

See also