---
sidebar_position: 11
---

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

# `lium up`

Create a new pod.

```bash
lium up [NODE_ID] [OPTIONS]
```

## Arguments

- `NODE_ID` — Node UUID, HUID, or index from the last [`lium ls`](./ls.md). Optional: when you omit it, the filter flags below narrow the list and the best node is picked **automatically**, with no menu — the only prompt is the confirmation before renting, which `--yes` skips.

## Options

### Selection & naming

| Flag | Effect |
|------|--------|
| `--name, -n NAME` | Custom pod name (auto-generated if not specified) |
| `--template_id, -t ID` | Specify template ID directly (skips template prompt) |
| `--gpu TYPE` | Filter nodes by GPU type (e.g. `H200`, `A6000`) |
| `--count, -c NUM` | Filter by number of GPUs per pod |
| `--country CODE` | Filter nodes by ISO country code (`US`, `FR`, …) |
| `--ports, -p NUM` | Only consider nodes with at least NUM available ports, and request NUM ports on the pod |
| `--yes, -y` | Skip confirmation prompt |
| `--no-ssh` | Create the pod and return, instead of opening an SSH session |

By default a successful `lium up` ends by opening an interactive SSH session to
the new pod (in `--image` mode it streams the container logs instead). Pass
`--no-ssh` when you want the command to return — in a script, or when you plan
to connect later with [`lium ssh`](./ssh.md).

### Auto-termination

| Flag | Effect |
|------|--------|
| `--ttl DURATION` | Auto-terminate after duration (e.g. `6h`, `45m`, `2d`) |
| `--until WHEN` | Auto-terminate at local time (`today 23:00`, `tomorrow 01:00`, `2026-05-08 15:30`) |

Use [`lium schedules`](./schedules.md) to view and cancel an existing schedule.

### Container

| Flag | Effect |
|------|--------|
| `--image IMAGE` | Docker image to run (e.g. `pytorch/pytorch:2.0`, `nvidia/cuda:12.0`) |
| `--dockerfile PATH` | Build the pod image from a local Dockerfile (custom build). Mutually exclusive with `--image` and `--template_id`. |
| `--internal-ports LIST` | Internal ports to expose (comma-separated, e.g. `22,8000,8080`) |
| `-e, --env KEY=VAL` | Environment variable; can be repeated |
| `--entrypoint CMD` | Override container entrypoint |
| `--cmd CMD` | Override container command |
| `--jupyter` | Install Jupyter Notebook (auto-selects an available port) |
| `--ssh-name NAME` | Name for a freshly registered SSH key (default: `cli-<user>@<hostname>`) |

**Custom Dockerfile builds** (`--dockerfile`): the image is built **on the node** from your Dockerfile — no build context is uploaded, so the Dockerfile must be self-contained. Network access is disabled during the build (`--network=none`) and `ADD <url>` / `ADD ${var}` directives are rejected. Keep the file under 64 KiB. The pod is SSH-accessible once the build finishes, just like a template-based pod. The `--env`, `--entrypoint`, `--cmd`, and `--internal-ports` flags don't apply here — define those in the Dockerfile itself.

### Volumes

| Flag | Effect |
|------|--------|
| `--volume, -v SPEC` | Volume spec — see below |
| `--volume-encryption` / `--no-volume-encryption` | Encrypt the local volume where the node supports it. Enabled by default. |

Volume spec forms:

- `id:<HUID>` — attach an existing volume by HUID
- `new:name=<NAME>[,desc=<DESC>]` — create and attach a new volume

### Restore from a backup

| Flag | Effect |
|------|--------|
| `--restore-backup BACKUP_ID` | Completed backup to restore after the pod starts |
| `--restore-to PATH` | New or empty directory below the pod's local volume mount |

The two restore flags must be used together. The pod becomes running and accessible before restoration finishes. Do not modify the restore directory until [`lium bk restore-logs`](./bk.md) reports completion.

## Examples

```bash
# Basic
lium up                                       # Auto-picks the best node, asks to confirm
lium up cosmic-hawk-f2                        # Specific node by HUID
lium up 1                                     # Node #1 from last ls
lium up --name dev-pod                        # Custom name

# Filtering nodes
lium up --gpu H200
lium up --gpu A6000 -c 2
lium up --gpu H200 --country FR
lium up --ports 5

# Auto-terminate
lium up --gpu H200 --ttl 6h                   # Stop after 6h
lium up --gpu H200 --until "tomorrow 09:00"   # Stop tomorrow morning

# Container customization
lium up 1 --image pytorch/pytorch:2.0
lium up 1 --image my-image -e API_KEY=xyz -e DEBUG=1
lium up 1 --internal-ports 22,8000,8080
lium up 1 --jupyter                           # Spin up with Jupyter

# Custom Dockerfile build (image built remotely from your Dockerfile)
lium up --gpu A6000 --dockerfile ./Dockerfile
lium up 1 --dockerfile ./Dockerfile --name my-build

# Volumes
lium up 1 --volume id:brave-fox-3a
lium up 1 --volume new:name=my-data,desc="Training data"

# Create a pod and restore a backup after it starts
lium up 1 --restore-backup 8fbb30f6 --restore-to /root/restored

# Direct template + skip prompt
lium up 1 --template_id abc123
lium up --gpu H200 --yes
```

## See also

- [`lium ls`](./ls.md) — find a node first
- [`lium templates`](./templates.md) — pick a template
- [`lium volumes`](./volumes.md) — pre-create a volume
- [`lium schedules`](./schedules.md) — manage `--ttl` / `--until` schedules