> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyceum.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Execution

> Run any OCI-compatible Docker container on Lyceum Cloud, with optional GPU

## Video Tutorial

<div className="flex justify-center">
  <video controls className="w-full rounded-lg" src="https://mintcdn.com/lyceum/qko2EiFIg1Uy6ET0/videos/docker-execution.mp4?fit=max&auto=format&n=qko2EiFIg1Uy6ET0&q=85&s=54a9446884538c6c9a71b6b72704b7d4" data-path="videos/docker-execution.mp4">
    Your browser does not support the video tag.
  </video>
</div>

<Info>
  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.
</Info>

## CLI

The `lyceum docker run` command mirrors `docker run` semantics.

```bash theme={null}
# 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`      | `cpu`     | Machine type, see [Machine Types](/docs/configuration/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

<Tabs>
  <Tab title="Docker Hub" icon="docker">
    ```bash theme={null}
    lyceum docker run myuser/private-image:tag \
      --registry-type basic \
      --registry-creds '{"username": "myuser", "password": "mytoken"}'
    ```
  </Tab>

  <Tab title="AWS ECR" icon="aws">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

For a printable cheat-sheet, run `lyceum docker registry-examples`.

### Streaming Logs Later

```bash theme={null}
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.

```bash theme={null}
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 (`cpu`, `gpu`, `gpu.a100`, `gpu.h100`, …). Defaults to `cpu`. |
| `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](/api-reference/introduction) for the complete schema and response shape.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Image pull errors" icon="download">
    * 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`
  </Accordion>

  <Accordion title="Authentication failed (HTTP 401)" icon="key">
    Run `lyceum auth login` to refresh your credentials, then retry.
  </Accordion>
</AccordionGroup>

<Note>
  Need help? Contact [support@lyceum.technology](mailto:support@lyceum.technology).
</Note>