Instance Management
The instance
command group allows you to create and manage full virtual machine instances on the Aleph Cloud network.
Overall Usage
aleph instance [OPTIONS] KEY_COMMAND [ARGS]...
Options
Command | Description |
---|---|
--help | Show the help prompt and exit |
Key Commands
Command | Description |
---|---|
create | Create a new VM instance |
delete | Delete an instance, unallocating all resources associated with it |
list | List all instances associated to an account |
reboot | Reboot an instance |
allocate | Notify a CRN to start an instance (for Pay-As-You-Go and confidential instances only) |
logs | Retrieve the logs of an instance |
stop | Stop an instance |
confidential-init-session | Initialize a confidential communication session with the VM |
confidential-start | Validate the authenticity of the VM and start it |
confidentia | Create (optional), start and unlock a confidential VM (all-in-one command) |
gpu | Create and register a new GPU instance on Aleph Cloud |
port-forwarder | Manage port forwarding for instances (list, create, update, delete, refresh) |
Creating an Instance
Create and register a new instance on Aleph Cloud. When you create an instance, port 22 (SSH) is automatically set up with TCP port forwarding to enable immediate SSH access to your instance.
Usage:
aleph instance create [OPTIONS]
Options
Options | Type | Description |
---|---|---|
--payment-type | [hold, superfluid, nft] | Payment method, either holding tokens, NFTs, or Pay-As-You-Go via token streaming |
--payment-chain | [AVAX, BASE, ETH, SOL] | Chain you want to use to pay for your instance |
--hypervisor | [qemu, firecracker] | Hypervisor to use to launch your instance. Always defaults to QEMU, since Firecracker is now deprecated for instances [default: qemu] |
--name | TEXT | Name of your new instance |
--rootfs | TEXT | Hash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it |
--compute-units | INTEGER | Number of compute units to allocate. Compute units correspond to a tier that includes vcpus, memory, disk and gpu presets. For reference, run: aleph pricing --help |
--vcpus | INTEGER | Number of virtual CPUs to allocate |
--memory | INTEGER | Maximum memory (RAM) in MiB to allocate |
--rootfs-size | INTEGER RANGE | Rootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125] |
--timeout-seconds | FLOAT | If vm is not called after [timeout_seconds] it will shutdown [default: 30.0] |
--ssh-pubkey-file | PATH | Path to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub] |
--address | TEXT | Address of the payer. In order to delegate the payment, your account must be authorized beforehand to publish on the behalf of this address. See the docs for more info: https://docs.aleph.cloud/protocol/permissions/ |
--crn-hash | TEXT | Hash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--crn-url | TEXT | URL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--confidential / --no-confidential | Launch a confidential instance (requires creating an encrypted volume) [default: no-confidential] | |
--confidential-firmware | TEXT | Hash to UEFI Firmware to launch confidential instance [default: ba5bb13f3abca960b101a759be162b229e2b7e93ecad9d1307e54de887f177ff] |
--gpu / --no-gpu | Launch an instance attaching a GPU to it [default: no-gpu] | |
--premium / --no-premium | Use Premium GPUs (VRAM > 48GiB) | |
--skip-volume / --no-skip-volume | Skip prompt to attach more volumes [default: no-skip-volume] | |
--persistent-volume | TEXT | Persistent volumes are allocated on the host machine and are not deleted when the VM is stopped. Requires at least name, mount path, and size_mib. To add multiple, reuse the same argument. Example: --persistent-volume name=data,mount=/opt/data,size_mib=1000. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/persistent/ |
--ephemeral-volume | TEXT | Ephemeral volumes are allocated on the host machine when the VM is started and deleted when the VM is stopped. Requires at least mount path and size_mib. To add multiple, reuse the same argument. Example: --ephemeral-volume mount=/opt/tmp,size_mib=100 |
--immutable-volume | TEXT | Immutable volumes are pinned on the network and can be used by multiple VMs at the same time. They are read-only and useful for setting up libraries or other dependencies. Requires at least mount path and ref (volume message hash). use_latest is True by default, to use the latest version of the volume, if it has been amended. To add multiple, reuse the same argument. Example: --immutable-volume mount=/opt/packages,ref=25a3...8d94. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/immutable/ |
--crn-auto-tac / --no-crn-auto-tac | Automatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac] | |
--channel | TEXT | Aleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS] |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--print-message / --no-print-message | Print the message after creation [default: no-print-message] | |
--verbose / --no-verbose | Display additional information [default: verbose] | |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Create an instance
aleph instance create
# Create an instance using hold payment and a specific config
aleph instance create \
--payment-type nft \
--payment-chain BASE \
--compute-units 1 \
--skip-volume \
--rootfs debian12 \
--name vm-nft
# Create an instance using PAYG and a speicif CRN
aleph instance create \
--payment-type superfluid \
--payment-chain BASE \
--compute-units 1 \
--skip-volume \
--rootfs debian12 \
--crn-url https://gpu-test-01.nergame.app \
--name vm-payg \
--crn-auto-tac
# Creating a confidential instance
aleph instance confidential \
--payment-type nft \
--payment-chain BASE \
--compute-units 1 \
--skip-volume \
--crn-url https://coco-1.crn.aleph.sh \
--no-keep-session \
--rootfs debian12 \
--name vm-confidential \
--crn-auto-tac
Deleting an Instance
Delete an instance, unallocating all resources associated with it. Associated VM will be stopped and erased. Immutable volumes will not be deleted.
Usage
aleph instance delete [OPTIONS] ITEM_HASH
Arguments
Argument | Type | Description |
---|---|---|
ITEM_HASH | ITEM HASH | Instance item hash to forget |
Options
Options | Type | Description |
---|---|---|
--reason | TEXT | Reason for deleting the instance [default: User deletion] |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--print-message / --no-print-message | Print the message after deletion [default: no-print-message] | |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Delete an instance
aleph instance delete ITEM_HASH
Listing Instances
List all instances associated to an account
Usage
aleph instance list [OPTIONS]
Options
Options | Type | Description |
---|---|---|
--address | TEXT | Owner address of the instances |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--json / --no-json | Print as json instead of rich table [default: no-json] | |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Listing your instances
aleph instance list
# Listing ADDRESS instances as json
aleph instance list --address ADDRESS --json
Rebooting an instance
Reboot an instance
Usage
aleph instance reboot [OPTIONS] VM_ID
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | VM item hash to reboot |
Options
Options | Type | Description |
---|---|---|
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Reboot an instance
aleph instance reboot VM ID
Allocate an instance
Notify a CRN to start an instance (for Pay-As-You-Go and confidential instances only)
Usage
aleph instance allocate [OPTIONS] VM_ID
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | VM item hash to allocate |
Options
Options | Type | Description |
---|---|---|
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Allocating an instance
aleph instance allocate VM ID
Check instance logs
Retrieve the logs of an instance
Usage
aleph instance logs [OPTIONS] VM_ID
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | VM item hash to retrieve the logs from |
Options
Options | Type | Description |
---|---|---|
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Retrieve logs of an instance
aleph instance logs VM ID
Stop an instance
Usage
aleph instance stop [OPTIONS] VM_ID
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | VM item hash to stop |
Options
Options | Type | Description |
---|---|---|
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Retrieve logs of an instance
aleph instance delete VM ID
Initialize a Confidential Communication
Initialize a confidential communication session with the VM
Usage
aleph instance confidential-init-session [OPTIONS] VM_ID
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | VM item hash to initialize the session for |
Options
Options | Type | Description |
---|---|---|
--domain | TEXT | Domain of the CRN where an associated VM is running. It ensures your VM will be stopped and erased on the CRN before the instance message is actually deleted |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--policy | INTEGER | Policy for the confidential session [default: 1] |
--keep-session / --no-keep-session | Keeping the already initiated session | |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Starting a confidential communication with a VM
aleph instance confidential-init-session VM_ID
Lauching a Confidential Instance
Create (optional), start and unlock a confidential VM (all-in-one command)
This command combines the following commands:
- create (unless vm_id is passed)
- allocate
- confidential-init-session
- confidential-start
Usage
aleph instance confidential [OPTIONS] [VM_ID]
Arguments
Argument | Type | Description |
---|---|---|
VM_ID | VM ID | Item hash of your VM. If provided, skip the instance creation, else create a new one |
Options
Option | Type | Description |
---|---|---|
--crn-url | TEXT | URL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--crn-hash | TEXT | Hash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--policy | INTEGER | Policy for the confidential session [default: 1] |
--confidential-firmware | TEXT | Hash to UEFI Firmware to launch confidential instance [default: ba5bb13f3abca960b101a759be162b229e2b7e93ecad9d1307e54de887f177ff] |
--firmware-hash | TEXT | Hash of the UEFI Firmware content, to validate measure (ignored if path is provided) [default: 89b76b0e64fe9015084fbffdf8ac98185bafc688bfe7a0b398585c392d03c7ee] |
--firmware-file | TEXT | Path to the UEFI Firmware content, to validate measure (instead of the hash) |
--keep-session / --no-keep-session | FLAG | Keeping the already initiated session |
--vm-secret | TEXT | Secret password to start the VM |
--payment-type | [hold, superfluid, nft] | Payment method, either holding tokens, NFTs, or Pay-As-You-Go via token streaming |
--chain | [ARB, AVAX, BASE, BLAST, BOB, BSC, CSDK, CYBER, DOT, ETH, FRAX, INK, LINEA, LISK, METIS, MODE, NEO, NULS, NULS2, OP, POL, SOL, TEZOS, WLD, ZORA] | Chain you are using to pay for your instance |
--name | TEXT | Name of your new instance |
--rootfs | TEXT | Hash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it |
--compute-units | INTEGER | Number of compute units to allocate. Compute units correspond to a tier that includes vcpus, memory, disk and gpu presets. For reference, run: aleph pricing --help |
--vcpus | INTEGER | Number of virtual CPUs to allocate |
--memory | INTEGER | Maximum memory (RAM) in MiB to allocate |
--rootfs-size | INTEGER RANGE | Rootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125] |
--timeout-seconds | FLOAT | If vm is not called after [timeout_seconds] it will shutdown [default: 30.0] |
--ssh-pubkey-file | PATH | Path to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub] |
--address | TEXT | Address of the payer. In order to delegate the payment, your account must be authorized beforehand to publish on the behalf of this address. See the docs for more info: https://docs.aleph.cloud/protocol/permissions/ |
--gpu / --no-gpu | FLAG | Launch an instance attaching a GPU to it [default: no-gpu] |
--premium / --no-premium | FLAG | Use Premium GPUs (VRAM > 48GiB) |
--skip-volume / --no-skip-volume | FLAG | Skip prompt to attach more volumes [default: no-skip-volume] |
--persistent-volume | TEXT | Persistent volumes are allocated on the host machine and are not deleted when the VM is stopped. Requires at least name, mount path, and size_mib. To add multiple, reuse the same argument. Example: --persistent-volume name=data,mount=/opt/data,size_mib=1000. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/persistent/ |
--ephemeral-volume | TEXT | Ephemeral volumes are allocated on the host machine when the VM is started and deleted when the VM is stopped. Requires at least mount path and size_mib. To add multiple, reuse the same argument. Example: --ephemeral-volume mount=/opt/tmp,size_mib=100 |
--immutable-volume | TEXT | Immutable volumes are pinned on the network and can be used by multiple VMs at the same time. They are read-only and useful for setting up libraries or other dependencies. Requires at least mount path and ref (volume message hash). use_latest is True by default, to use the latest version of the volume, if it has been amended. To add multiple, reuse the same argument. Example: --immutable-volume mount=/opt/packages,ref=25a3...8d94. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/immutable/ |
--crn-auto-tac / --no-crn-auto-tac | FLAG | Automatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac] |
--channel | TEXT | Aleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS] |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--debug / --no-debug | FLAG | Enable debug logging [default: no-debug] |
--help | FLAG | Show this message and exit |
# Create a basic confidential VM with default settings
aleph instance confidential \
--name secure-vm \
--payment-type hold \
--payment-chain ETH
# Create a confidential VM using a CRN and keep the session alive
aleph instance confidential \
--name confidential-db \
--crn-url https://example.com/my-crn \
--crn-hash 123abc456def \
--keep-session \
--payment-type superfluid \
--payment-chain BASE
# Convert an existing instance to a confidential one
aleph instance confidential VM_HASH
# Create a confidential VM with a persistent volume and a VM startup secret
aleph instance confidential \
--name private-ai-node \
--vm-secret mySecret \
--persistent-volume name=ai_data,mount=/data,size_mib=8000 \
--payment-type nft \
--payment-chain SOL
Create a GPU Instance
Usage
aleph instance gpu [OPTIONS]
Options
Option | Type | Description |
---|---|---|
--payment-chain | [AVAX, BASE] | Chain you want to use to pay for your instance |
--name | TEXT | Name of your new instance |
--rootfs | TEXT | Hash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it |
--compute-units | INTEGER | Number of compute units to allocate. Compute units correspond to a tier that includes vcpus, memory, disk and gpu presets. For reference, run: aleph pricing --help |
--vcpus | INTEGER | Number of virtual CPUs to allocate |
--memory | INTEGER | Maximum memory (RAM) in MiB to allocate |
--rootfs-size | INTEGER RANGE | Rootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125] |
--premium / --no-premium | Use Premium GPUs (VRAM > 48GiB) | |
--timeout-seconds | FLOAT | If vm is not called after [timeout_seconds] it will shutdown [default: 30.0] |
--ssh-pubkey-file | PATH | Path to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub] |
--address | TEXT | Address of the payer. In order to delegate the payment, your account must be authorized beforehand to publish on the behalf of this address. See the docs for more info: https://docs.aleph.cloud/protocol/permissions/ |
--crn-hash | TEXT | Hash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--crn-url | TEXT | URL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances) |
--skip-volume / --no-skip-volume | Skip prompt to attach more volumes [default: no-skip-volume] | |
--persistent-volume | TEXT | Persistent volumes are allocated on the host machine and are not deleted when the VM is stopped. Requires at least name, mount path, and size_mib. To add multiple, reuse the same argument. Example: --persistent-volume name=data,mount=/opt/data,size_mib=1000. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/persistent/ |
--ephemeral-volume | TEXT | Ephemeral volumes are allocated on the host machine when the VM is started and deleted when the VM is stopped. Requires at least mount path and size_mib. To add multiple, reuse the same argument. Example: --ephemeral-volume mount=/opt/tmp,size_mib=100 |
--immutable-volume | TEXT | Immutable volumes are pinned on the network and can be used by multiple VMs at the same time. They are read-only and useful for setting up libraries or other dependencies. Requires at least mount path and ref (volume message hash). use_latest is True by default, to use the latest version of the volume, if it has been amended. To add multiple, reuse the same argument. Example: --immutable-volume mount=/opt/packages,ref=25a3...8d94. For more info, see the docs: https://docs.aleph.cloud/computing/volumes/immutable/ |
--crn-auto-tac / --no-crn-auto-tac | Automatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac] | |
--channel | TEXT | Aleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS] |
--private-key | TEXT | Your private key. Cannot be used with --private-key-file |
--private-key-file | PATH | Path to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key] |
--print-message / --no-print-message | Print the message after creation [default: no-print-message] | |
--verbose / --no-verbose | Display additional information [default: verbose] | |
--debug / --no-debug | Enable debug logging [default: no-debug] | |
--help | Show this message and exit |
# Create a basic GPU instance with default settings (Ubuntu rootfs, minimal resources)
aleph instance gpu \
--name basic-gpu \
--payment-chain AVAX
# Create a GPU instance with custom CPU/RAM and a pinned rootfs
aleph instance gpu \
--name custom-gpu \
--vcpus 8 \
--memory 16384 \
--rootfs RootfsHash \
--payment-chain BASE
# Create a premium GPU instance and a specific CRN
aleph instance gpu \
--name full-stack-gpu \
--vcpus 12 \
--memory 32768 \
--rootfs-size 30000 \
--crn-url CRN_URL \
--crn-hash CRN_HASH \
--premium \
--payment-chain AVAX
Troubleshooting
Common issues and solutions:
- Instance not starting: Check resource allocation and system compatibility
- SSH connection failures: Verify your SSH key was properly added and the instance is running
- Performance issues: Consider increasing CPU, memory, or using a GPU instance
- Payment errors: Ensure you have sufficient ALEPH tokens for staking or PAYG balance
Related Commands
For detailed documentation on port forwarding functionality, see the port-forwarder documentation.