Skip to main content

​
Video Tutorial

Bring your own image from Docker Hub, AWS ECR, or any private registry. Containers run with optional GPU acceleration and stream output back to you in real time.

​
CLI

The lyceum docker run command mirrors docker run semantics. 
# Public image, CPU
lyceum docker run python:3.11 -c "python -c 'print(1+1)'"

# Override the entrypoint and pass environment variables
lyceum docker run myapp:latest -e "DEBUG=true" -e "API_KEY=secret"

# GPU workload, detached
lyceum docker run nvidia/cuda:12.0-base -m gpu.a100 -d
By default the command streams container output until completion. Pass -d / --detach to return immediately and reconnect later with lyceum docker logs <execution_id>.

​
Flags

FlagDefaultDescription
image (positional)—Docker image reference, e.g. python:3.11 or myregistry.com/img:tag
-m, --machinecpuMachine type — see Machine Types
-t, --timeout300Execution timeout in seconds
-c, --command—Command to run inside the container (single string, parsed shell-style)
-e, --env—Environment variable as KEY=value (repeatable)
-f, --file-name—Friendly name for the execution
-d, --detachfalseReturn immediately after starting the container
--callback—Webhook URL notified on completion
--registry-creds—Private registry credentials as a JSON string
--registry-type—Credential type: basic or aws
--s3 / --no-s3--s3Mount your S3 storage inside the container
--s3-mount-path/mnt/s3Path inside the container where S3 is mounted
--graceful-timeout—Seconds to wait for graceful shutdown on cancel

​
Private Registries

lyceum docker run myuser/private-image:tag \
  --registry-type basic \
  --registry-creds '{"username": "myuser", "password": "mytoken"}'
For a printable cheat-sheet, run lyceum docker registry-examples.

​
Streaming Logs Later

lyceum docker logs 9d73319c-6f1c-4b4c-90e4-044244353ce4
Ctrl+C only disconnects from the log stream — it does not cancel the running execution.

​
API

The CLI is a thin wrapper around POST /api/v2/external/execution/image/start. Use the API directly when integrating with custom orchestration. 
curl -X POST https://api.lyceum.technology/api/v2/external/execution/image/start \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "docker_image_ref": "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime",
    "docker_run_cmd": ["python", "train.py"],
    "execution_type": "gpu.a100",
    "timeout": 3600
  }'

​
Request fields

FieldTypeDescription
docker_image_refstring (required)Fully qualified image reference
execution_typestringMachine type (cpu, gpu, gpu.a100, gpu.h100, …). Defaults to cpu.
docker_run_cmdstring[]Override container command
docker_run_envstringEnvironment variables, newline-separated KEY=VALUE pairs
timeoutintegerMaximum execution time in seconds
docker_registry_credential_typestringbasic or aws
docker_username / docker_passwordstringBasic registry credentials
aws_access_key_id / aws_secret_access_key / aws_session_token / aws_regionstringAWS ECR credentials
enable_s3_mountboolMount user S3 storage inside the container
s3_mount_pathstringMount path (default /mnt/s3)
user_callback_urlsstring[]Webhook URLs for streamed output
graceful_timeoutintegerSeconds to wait for graceful shutdown on cancel
file_namestringFriendly name for the execution
See the API Reference for the complete schema and response shape.

​
Troubleshooting

  • Verify the image name and tag exist
  • Check registry credentials and --registry-type
  • Ensure the image is built for linux/amd64
  • Test the pull locally first: docker pull your-image:tag
Run lyceum auth login to refresh your credentials, then retry.
Need help? Contact info@lyceum.technology.