Docker Execution

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

Flag	Default	Description
`image` (positional)	—	Docker image reference, e.g. `python:3.11` or `myregistry.com/img:tag`
`-m, --machine`	`gpu.a100`	Machine type, see Machine Types
`-t, --timeout`	`300`	Execution 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, --detach`	`false`	Return 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`	`--s3`	Mount your S3 storage inside the container
`--s3-mount-path`	`/mnt/s3`	Path inside the container where S3 is mounted
`--graceful-timeout`	—	Seconds to wait for graceful shutdown on cancel

Private Registries

Docker Hub
AWS ECR

lyceum docker run myuser/private-image:tag \
  --registry-type basic \
  --registry-creds '{"username": "myuser", "password": "mytoken"}'

lyceum docker run 123456789012.dkr.ecr.us-west-2.amazonaws.com/myapp:latest \
  --registry-type aws \
  --registry-creds '{
    "region": "us-west-2",
    "aws_access_key_id": "AKIAI...",
    "aws_secret_access_key": "wJalrX..."
  }'

An aws_session_token field can be added if you use temporary credentials.

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

Field	Type	Description
`docker_image_ref`	string (required)	Fully qualified image reference
`execution_type`	string	Machine type (`gpu.a100`, `gpu.h100`, …). Defaults to `gpu.a100`.
`docker_run_cmd`	string[]	Override container command
`docker_run_env`	string	Environment variables, newline-separated `KEY=VALUE` pairs
`timeout`	integer	Maximum execution time in seconds
`docker_registry_credential_type`	string	`basic` or `aws`
`docker_username` / `docker_password`	string	Basic registry credentials
`aws_access_key_id` / `aws_secret_access_key` / `aws_session_token` / `aws_region`	string	AWS ECR credentials
`enable_s3_mount`	bool	Mount user S3 storage inside the container
`s3_mount_path`	string	Mount path (default `/mnt/s3`)
`user_callback_urls`	string[]	Webhook URLs for streamed output
`graceful_timeout`	integer	Seconds to wait for graceful shutdown on cancel
`file_name`	string	Friendly name for the execution

See the API Reference for the complete schema and response shape.

Troubleshooting

Image pull errors

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

Authentication failed (HTTP 401)

Run lyceum auth login to refresh your credentials, then retry.

Need help? Contact support@lyceum.technology.

Getting Started

Serverless

Instances

Inference

Coding Agents

Workloads

Observability

Tools

Configuration

Account

Video Tutorial

CLI

Flags

Private Registries

Streaming Logs Later

API

Request fields

Troubleshooting

​Video Tutorial

​CLI

​Flags

​Private Registries

​Streaming Logs Later

​API

​Request fields

​Troubleshooting

Video Tutorial

CLI

Flags

Private Registries

Streaming Logs Later

API

Request fields

Troubleshooting