> ## 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 create

> Create a resource

Create a resource.

Resource types:

* deployment
* replicaset
* pod
* job
* sandbox
* vm
* cronjob
* service
* webapp
* gateway
* httproute
* tlsroute
* referencegrant
* secret

Most workload resources are created from YAML manifests. Sandboxes can also be
created imperatively from an image, TTL, and target subnet. If --name is omitted
for an imperative Sandbox create, the CLI generates a concrete Sandbox name
before sending the request. Services and WebApps are created imperatively from
their Deployment and Service-port references, and the gateway family
(gateways, HTTP and TLS routes, reference grants) from flags.

## Usage

```bash theme={null}
idyl create [resource]
```

## Commands

| Command                      | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `idyl create cronjob`        | Create a cronjob from a file                             |
| `idyl create deployment`     | Create a deployment from a file                          |
| `idyl create gateway`        | Create a Gateway claiming ingress hostnames              |
| `idyl create httproute`      | Create an HTTPRoute from a Gateway to a Service port     |
| `idyl create job`            | Create a job from a file                                 |
| `idyl create pod`            | Create a pod from a file                                 |
| `idyl create referencegrant` | Create a ReferenceGrant admitting cross-namespace routes |
| `idyl create replicaset`     | Create a replicaset from a file                          |
| `idyl create sandbox`        | Create a disposable Sandbox                              |
| `idyl create secret`         | Create a secret                                          |
| `idyl create service`        | Create a Service over a Deployment port                  |
| `idyl create tlsroute`       | Create a TLSRoute from a Gateway to a Service port       |
| `idyl create vm`             | Create a VirtualMachine                                  |
| `idyl create webapp`         | Create a WebApp for a Service port                       |

## 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. |
| `-n <string>, --namespace <string>`  | Namespace to use for this command.                                 |
| `-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.                               |
| `--subnet <string>`                  | Override the context subnet for this command.                      |

## Examples

```bash theme={null}
# Create a deployment from a manifest
idyl create deployment -f deployment.yaml

# Create a Sandbox with a generated name
idyl create sandbox --image ubuntu:24.04 --ttl 2h --subnet <subnet>

# Create a Sandbox with an explicit name and isolation class
idyl create sandbox --name dev --image ubuntu:24.04 --ttl 24h --subnet <subnet> --isolation-class secure-container

# Create a VirtualMachine with a durable root disk
idyl create vm --image ubuntu:26.04 --cpu 4 --mem 4Gi --disk 100Gi --subnet <subnet>

# Create a registry credential secret
printf '%s' "$GHCR_TOKEN" | idyl create secret registry ghcr-prod --registry ghcr.io --username <username> --password-stdin --subnet <subnet>

# Publish a Deployment through a generated WebApp hostname
idyl create service --name chat-api --target deployment/chat-api --port http=8080 --subnet <subnet>
idyl create webapp --name chat-api --service chat-api:http --subnet <subnet>
```

## Subcommand reference

### `idyl create cronjob`

Create a cronjob from a file

#### Usage

```bash theme={null}
idyl create cronjob [flags]
```

#### Aliases

* `cronjobs`
* `cj`

#### Flags

| Flag                                | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f <string>, --filename <string>`  | Required. Path to the file containing the cronjob definition.                                     |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                   |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                |
| `--subnet <string>`                 | Subnet for workload placement, overriding the current context.                                    |

### `idyl create deployment`

Create a deployment from a file

#### Usage

```bash theme={null}
idyl create deployment [flags]
```

#### Aliases

* `deployments`
* `deploy`

#### Flags

| Flag                                | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f <string>, --filename <string>`  | Required. Path to the file containing the deployment definition.                                  |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                   |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                |
| `--subnet <string>`                 | Subnet for workload placement, overriding the current context.                                    |

### `idyl create gateway`

Create a Gateway that claims public ingress hostnames.

Each --hostname becomes one HTTPS listener terminated by the platform with
managed certificates; HTTPRoutes attach to it. Each --tls-hostname becomes
one TLS passthrough listener that forwards the client's TLS bytes to the
workload; TLSRoutes attach to it.

#### Usage

```bash theme={null}
idyl create gateway --name <name> --hostname <hostname> --subnet <subnet> [flags]
```

#### Aliases

* `gateways`
* `gw`

#### Flags

| Flag                                | Description                                                |
| ----------------------------------- | ---------------------------------------------------------- |
| `--hostname <stringArray>`          | Hostname served by an HTTPS listener; repeatable.          |
| `--name <string>`                   | Required. Gateway name.                                    |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.            |
| `--subnet <string>`                 | Subnet where the Gateway should run.                       |
| `--tls-hostname <stringArray>`      | Hostname served by a TLS passthrough listener; repeatable. |

#### Examples

```bash theme={null}
idyl create gateway --name web --hostname app.example.com --subnet <subnet>
idyl create gateway --name edge --hostname app.example.com --hostname api.example.com --tls-hostname db.example.com --subnet <subnet>
```

### `idyl create httproute`

Create an HTTPRoute that routes HTTP traffic from a Gateway's HTTPS
listeners to one Service port by hostname and path.

\--port names a Service port, never a number. Route hostnames are
intersected with the listener's hostname at admission.

#### Usage

```bash theme={null}
idyl create httproute --name <name> --parent <gateway> --hostname <hostname> --service <service> --port <portName> --subnet <subnet> [flags]
```

#### Aliases

* `httproutes`

#### Flags

| Flag                                | Description                                                                |
| ----------------------------------- | -------------------------------------------------------------------------- |
| `--hostname <stringArray>`          | Required. Hostname the route serves; repeatable.                           |
| `--name <string>`                   | Required. HTTPRoute name.                                                  |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                            |
| `--parent <string>`                 | Required. Gateway the route attaches to.                                   |
| `--path <string>`                   | Request path the rule matches.                                             |
| `--path-type <string>`              | Path match type (PathPrefix\|Exact). Default: `PathPrefix`.                |
| `--port <string>`                   | Required. Service port name on the backend.                                |
| `--section <string>`                | Gateway listener name to attach to. Defaults to every compatible listener. |
| `--service <string>`                | Required. Service backend name.                                            |
| `--subnet <string>`                 | Subnet where the HTTPRoute should run.                                     |

#### Examples

```bash theme={null}
idyl create httproute --name web --parent edge --hostname app.example.com --service chat-api --port http --subnet <subnet>
idyl create httproute --name api --parent edge --section web-0 --hostname app.example.com --service chat-api --port http --path /api --path-type PathPrefix --subnet <subnet>
```

### `idyl create job`

Create a job from a file

#### Usage

```bash theme={null}
idyl create job [flags]
```

#### Aliases

* `jobs`

#### Flags

| Flag                                | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f <string>, --filename <string>`  | Required. Path to the file containing the job definition.                                         |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                   |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                |
| `--subnet <string>`                 | Subnet for workload placement, overriding the current context.                                    |

### `idyl create pod`

Create a pod from a file

#### Usage

```bash theme={null}
idyl create pod [flags]
```

#### Aliases

* `pods`

#### Flags

| Flag                                | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f <string>, --filename <string>`  | Required. Path to the file containing the pod definition.                                         |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                   |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                |
| `--subnet <string>`                 | Subnet for workload placement, overriding the current context.                                    |

### `idyl create referencegrant`

Create a ReferenceGrant that permits routes in another namespace to
reference Services in the grant's own namespace.

The grant lives in the target namespace and grants inward; absent a grant,
a cross-namespace reference fails closed. Omit --to-service to cover every
Service in the namespace.

#### Usage

```bash theme={null}
idyl create referencegrant --name <name> --from-kind <HTTPRoute|TLSRoute> --from-namespace <namespace> --subnet <subnet> [flags]
```

#### Aliases

* `referencegrants`

#### Flags

| Flag                                | Description                                                           |
| ----------------------------------- | --------------------------------------------------------------------- |
| `--from-kind <string>`              | Required. Route kind the grant admits (HTTPRoute or TLSRoute).        |
| `--from-namespace <string>`         | Required. Namespace the granted routes originate from.                |
| `--name <string>`                   | Required. ReferenceGrant name.                                        |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                       |
| `--subnet <string>`                 | Subnet where the ReferenceGrant should live.                          |
| `--to-service <string>`             | Service the grant covers. Defaults to every Service in the namespace. |

#### Examples

```bash theme={null}
idyl create referencegrant --name from-web --from-kind HTTPRoute --from-namespace web --subnet <subnet>
idyl create referencegrant --name from-edge --from-kind TLSRoute --from-namespace edge --to-service postgres --subnet <subnet>
```

### `idyl create replicaset`

Create a replicaset from a file

#### Usage

```bash theme={null}
idyl create replicaset [flags]
```

#### Aliases

* `replicasets`
* `rs`

#### Flags

| Flag                                | Description                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f <string>, --filename <string>`  | Required. Path to the file containing the replicaset definition.                                  |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                   |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                |
| `--subnet <string>`                 | Subnet for workload placement, overriding the current context.                                    |

### `idyl create sandbox`

Create a disposable Sandbox workload inside an IDYL subnet.

Provide a container image, a required TTL duration, and a target subnet. TTL
uses duration strings such as 15m, 2h, or 24h. If --name is omitted, the CLI
generates a concrete Sandbox name before sending the create request.

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

By default, IDYL keeps the Sandbox open until its TTL expires or it is deleted. Use
\--use-image-entrypoint to let the image ENTRYPOINT/CMD control the process, or
\--command with optional --args to run an explicit command.

Use --isolation-class container, secure-container, or microvm to request the
Sandbox pod template isolation class when that value is allowed by the target
subnet.

#### Usage

```bash theme={null}
idyl create sandbox --image <image> --ttl <duration> --subnet <subnet> [--name <name>] [flags]
```

#### Aliases

* `sandboxes`

#### 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 <string>`                      | Required. Container image URI for the Sandbox pod template.                                               |
| `--image-pull-secret <string>`          | Stored image pull secret reference (secret://name or secret://namespace/name).                            |
| `--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>`                       | Sandbox name. If omitted, the CLI generates a concrete name before creating the Sandbox.                  |
| `-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 where the Sandbox should run.                                                                      |
| `--ttl <string>`                        | Required. Sandbox TTL duration, such as 15m, 2h, or 24h.                                                  |
| `--use-image-entrypoint`                | Use the image ENTRYPOINT and CMD lifecycle instead of holding the Sandbox open.                           |

#### Examples

```bash theme={null}
# Create a Sandbox with a generated name
idyl create sandbox --image ubuntu:24.04 --ttl 2h --subnet <subnet>

# Create a Sandbox that uses the image ENTRYPOINT/CMD
idyl create sandbox --image my-image --ttl 2h --subnet <subnet> --use-image-entrypoint

# Create a Sandbox that runs an explicit command
idyl create sandbox --image my-image --ttl 2h --subnet <subnet> --command "/app/dev-server" --args "--port 8080"

# Create a named Sandbox that requests secure-container isolation
idyl create sandbox --name dev --image ubuntu:24.04 --ttl 24h --subnet <subnet> --isolation-class secure-container

# Create a Sandbox from a private registry using a stored secret
idyl create sandbox --image ghcr.io/acme/dev:latest --ttl 2h --subnet <subnet> --image-pull-secret secret://ghcr-prod
```

### `idyl create secret`

Create a subnet-bound secret in the selected account and namespace.

Secrets are stored through the authenticated subnet API host and are redacted
on management reads.

#### Usage

```bash theme={null}
idyl create secret
```

#### Aliases

* `secrets`

#### Commands

| Command                       | Description                         |
| ----------------------------- | ----------------------------------- |
| `idyl create secret registry` | Create a registry credential secret |

#### Examples

```bash theme={null}
# Create a registry credential from stdin
printf '%s' "$GHCR_TOKEN" | idyl create secret registry ghcr-prod --registry ghcr.io --username <username> --password-stdin --subnet <subnet>
```

### `idyl create secret registry`

Create a subnet-bound registry credential secret for private image pulls.

The registry password is accepted only from stdin or an interactive hidden
prompt. There is intentionally no --password flag.

#### Usage

```bash theme={null}
idyl create secret registry <name> [flags]
```

#### Flags

| Flag                                | Description                                            |
| ----------------------------------- | ------------------------------------------------------ |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.        |
| `-o <string>, --output <string>`    | Output format: table, json, or yaml. Default: `table`. |
| `--password-stdin`                  | Read the registry password from stdin.                 |
| `--registry <string>`               | Required. Registry host, such as ghcr.io.              |
| `--repository-prefix <stringArray>` | Allowed repository prefix; repeatable.                 |
| `--subnet <string>`                 | Subnet for the secret.                                 |
| `--username <string>`               | Required. Registry username.                           |

#### Examples

```bash theme={null}
# Create a GHCR credential from stdin
printf '%s' "$GHCR_TOKEN" | idyl create secret registry ghcr-prod --registry ghcr.io --username <username> --password-stdin --subnet <subnet>

# Create a credential scoped by repository prefixes
idyl create secret registry ghcr-prod --registry ghcr.io --username <username> --repository-prefix acme-corp/private-api --password-stdin --subnet <subnet>
```

### `idyl create service`

Create a Service that defines a stable named HTTP port over one
Deployment target.

#### Usage

```bash theme={null}
idyl create service --name <name> --target deployment/<deploymentName> --port <portName>=<targetPort> --subnet <subnet> [flags]
```

#### Aliases

* `services`

#### Flags

| Flag                                | Description                                                      |
| ----------------------------------- | ---------------------------------------------------------------- |
| `--name <string>`                   | Required. Service name.                                          |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                  |
| `--port <stringArray>`              | Required. HTTP Service port in name=targetPort form; repeatable. |
| `--subnet <string>`                 | Subnet where the Service should run.                             |
| `--target <string>`                 | Required. Deployment target in deployment/\<name> form.          |

#### Examples

```bash theme={null}
idyl create service --name chat-api --target deployment/chat-api --port http=8080 --subnet <subnet>
idyl create service --name api --target deployment/api --port http=8080 --port metrics=9090 --subnet <subnet>
```

### `idyl create tlsroute`

Create a TLSRoute that routes TLS traffic from a Gateway's TLS
passthrough listeners to one Service port by SNI hostname. The client's TLS
runs end-to-end to the workload.

\--port names a Service port, never a number.

#### Usage

```bash theme={null}
idyl create tlsroute --name <name> --parent <gateway> --hostname <hostname> --service <service> --port <portName> --subnet <subnet> [flags]
```

#### Aliases

* `tlsroutes`

#### Flags

| Flag                                | Description                                          |
| ----------------------------------- | ---------------------------------------------------- |
| `--hostname <stringArray>`          | Required. SNI hostname the route serves; repeatable. |
| `--name <string>`                   | Required. TLSRoute name.                             |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.      |
| `--parent <string>`                 | Required. Gateway the route attaches to.             |
| `--port <string>`                   | Required. Service port name on the backend.          |
| `--service <string>`                | Required. Service backend name.                      |
| `--subnet <string>`                 | Subnet where the TLSRoute should run.                |

#### Examples

```bash theme={null}
idyl create tlsroute --name db --parent edge --hostname db.example.com --service postgres --port pg --subnet <subnet>
```

### `idyl create vm`

Create a durable VirtualMachine inside an IDYL subnet.

The CLI sends the VM image alias as supplied, such as ubuntu:26.04. Image
aliases are resolved by the platform before node assignment; the CLI does not
resolve aliases to artifact URLs.

If --name is omitted, the CLI generates a concrete VirtualMachine name before
sending the request.

#### Usage

```bash theme={null}
idyl create vm --image <image> --cpu <cpu> --mem <memory> --disk <size> --subnet <subnet> [--name <name>] [flags]
```

#### Aliases

* `vms`
* `virtualmachine`
* `virtualmachines`

#### Flags

| Flag                                | Description                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `--cpu <string>`                    | Required. VM CPU request, such as 500m, 2, or 4.                                                       |
| `--disk <string>`                   | Required. Durable root disk size, such as 20Gi or 100Gi.                                               |
| `--fleet <string>`                  | Constrain scheduling to eligible members of this fleet within the workload's subnet, by fleet ID.      |
| `--hostname <string>`               | Guest hostname for first boot.                                                                         |
| `--image <string>`                  | Required. Curated VM image alias, such as ubuntu:26.04.                                                |
| `--mem <string>`                    | Required. VM memory request, such as 1Gi or 4096Mi.                                                    |
| `--name <string>`                   | VirtualMachine name. If omitted, the CLI generates a concrete name before creating the VirtualMachine. |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.                                                        |
| `--network-class <string>`          | VM network class: none or unrestricted.                                                                |
| `--node <string>`                   | Constrain scheduling to this single node within the workload's subnet, by node ID.                     |
| `--platform <string>`               | Guest platform, such as linux/amd64.                                                                   |
| `--ssh-key <stringArray>`           | SSH public key to inject at first boot; repeatable.                                                    |
| `--subnet <string>`                 | Subnet where the VirtualMachine should run.                                                            |
| `--user-data-ref <string>`          | Secret reference for cloud-init user-data (secret://name or secret://namespace/name).                  |

#### Examples

```bash theme={null}
# Create a VirtualMachine with a generated name
idyl create vm --image ubuntu:26.04 --cpu 4 --mem 4Gi --disk 100Gi --subnet <subnet>

# Create a named VirtualMachine with an unrestricted network
idyl create vm --name dev-vm --image ubuntu:26.04 --cpu 2 --mem 2Gi --disk 40Gi --subnet <subnet> --network-class unrestricted
```

### `idyl create webapp`

Create a WebApp that publishes one Service port through an
IDYL-generated HTTPS hostname.

#### Usage

```bash theme={null}
idyl create webapp --name <name> --service <serviceName>:<portName> --subnet <subnet> [flags]
```

#### Aliases

* `webapps`

#### Flags

| Flag                                | Description                                          |
| ----------------------------------- | ---------------------------------------------------- |
| `--name <string>`                   | Required. WebApp name.                               |
| `-n <string>, --namespace <string>` | Namespace name, overriding the current context.      |
| `--service <string>`                | Required. Service port in serviceName:portName form. |
| `--subnet <string>`                 | Subnet where the WebApp should run.                  |

#### Examples

```bash theme={null}
idyl create webapp --name chat-api --service chat-api:http --subnet <subnet>
```