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

# idyl run

> Run a standalone pod for debugging or testing

Run a standalone pod with debugging-friendly defaults.
Unlike 'deploy', this creates a Pod directly rather than a Deployment.

Interactive mode (-i, -t) is not supported.

Command and args values are split using shell-style quoting, so quoted
substrings stay together as one container argument.

Use --platform, --isolation-class, and --network-class to declare workload
runtime intent. Admission and scheduling still require a target subnet policy
and provider nodes that match the requested runtime capabilities.

For isolated secure-container admission, declare linux/amd64, secure-container
isolation, and a network class of none or restricted-egress. The CLI records
this intent; the platform validates it before scheduling.

## Usage

```bash theme={null}
idyl run IMAGE [flags]
```

## Flags

| Flag                                    | Description                                                                                               |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--args <string>`                       | Override the container CMD arguments, split as shell-style words.                                         |
| `--command <string>`                    | Override the container ENTRYPOINT, split as shell-style words.                                            |
| `--cpu <string>`                        | CPU limit, such as 100m or 0.5. Defaults to the configured value.                                         |
| `-e <stringArray>, --env <stringArray>` | Environment variable in KEY=VALUE form; repeatable.                                                       |
| `--fleet <string>`                      | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID.         |
| `--gpu <string>`                        | GPU requirement, such as rtx5090, 2:h100, or nvidia:24Gi.                                                 |
| `--image-pull-secret <string>`          | Stored image pull secret reference (secret://name or secret://namespace/name).                            |
| `-i, --interactive`                     | Keep stdin open. Interactive mode is not supported.                                                       |
| `--isolation-class <string>`            | Workload isolation class (container, secure-container, or microvm); must be allowed by the target subnet. |
| `--memory <string>`                     | Memory limit, such as 128Mi or 512Mi. Defaults to the configured value.                                   |
| `--name <string>`                       | Name for the pod. Auto-generated if omitted.                                                              |
| `-n <string>, --namespace <string>`     | Namespace name, overriding the current context.                                                           |
| `--network-class <string>`              | Workload network class: none, restricted-egress, or unrestricted.                                         |
| `--node <string>`                       | Constrain scheduling to this single node within the workload's subnet, by node ID.                        |
| `--platform <string>`                   | Target workload platform: linux/amd64 or linux/arm64.                                                     |
| `--subnet <string>`                     | Subnet for workload placement.                                                                            |
| `-t, --tty`                             | Allocate a pseudo-TTY. Interactive mode is not supported.                                                 |

## Inherited flags

| Flag                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `-a <string>, --account-id <string>` | Account ID to use, overriding the current context.                 |
| `-c <string>, --context <string>`    | Use the named context for this command.                            |
| `--homedir <string>`                 | Override the configuration directory. Defaults to \~/.config/idyl. |
| `-o <string>, --output <string>`     | Output format (json\|yaml).                                        |
| `-p <string>, --profile <string>`    | Override the access profile for this command.                      |
| `--realm <string>`                   | Override the realm for this command.                               |

## Examples

```bash theme={null}
# Run nginx with auto-generated name
idyl run nginx

# Run with custom name
idyl run alpine --name=debug-tool

# Run with command and args
idyl run busybox --command="echo" --args="hello world"

# Run with resource limits
idyl run myapp:debug --cpu=100m --memory=128Mi

# Run with GPU requirements
idyl run nvidia/cuda:12.0 --gpu=rtx5090
idyl run ollama --gpu="nvidia:24Gi"

# Declare container isolation intent
idyl run nginx --platform linux/amd64 --isolation-class container

# Declare secure-container isolation intent
idyl run nginx --platform linux/amd64 --isolation-class secure-container

# Use the subnet default isolation class, when configured by runtime policy
idyl run nginx --subnet=secure-subnet --platform linux/amd64

# Declare isolated secure-container intent with no workload network
idyl run nginx --platform linux/amd64 --isolation-class secure-container --network-class none

# Declare microvm isolation intent (single container, enforced networking)
idyl run nginx --platform linux/amd64 --isolation-class microvm --network-class none

# Run in a subnet
idyl run nginx --subnet=my-subnet

# Run from a private registry using a stored secret
idyl run ghcr.io/acme/private-api:latest --image-pull-secret secret://ghcr-prod --subnet=my-subnet
```