Skip to content

Instance Management

The instance command group allows you to create and manage full virtual machine instances on the Aleph Cloud network.

Overall Usage

bash
aleph instance [OPTIONS] KEY_COMMAND [ARGS]...

Options

CommandDescription
--helpShow the help prompt and exit

Key Commands

CommandDescription
createCreate a new VM instance
deleteDelete an instance, unallocating all resources associated with it
listList all instances associated to an account
rebootReboot an instance
allocateNotify a CRN to start an instance (for Pay-As-You-Go and confidential instances only)
logsRetrieve the logs of an instance
stopStop an instance
confidential-init-sessionInitialize a confidential communication session with the VM
confidential-startValidate the authenticity of the VM and start it
confidentiaCreate (optional), start and unlock a confidential VM (all-in-one command)
gpuCreate and register a new GPU instance on Aleph Cloud

Creating an Instance

Create and register a new instance on Aleph Cloud

Usage:

bash
aleph instance create [OPTIONS]

Options

OptionsTypeDescription
--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]
--nameTEXTName of your new instance
--rootfsTEXTHash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it
--compute-unitsINTEGERNumber 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
--vcpusINTEGERNumber of virtual CPUs to allocate
--memoryINTEGERMaximum memory (RAM) in MiB to allocate
--rootfs-sizeINTEGER RANGERootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125]
--timeout-secondsFLOATIf vm is not called after [timeout_seconds] it will shutdown [default: 30.0]
--ssh-pubkey-filePATHPath to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub]
--addressTEXTAddress 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-hashTEXTHash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--crn-urlTEXTURL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--confidential / --no-confidentialLaunch a confidential instance (requires creating an encrypted volume) [default: no-confidential]
--confidential-firmwareTEXTHash to UEFI Firmware to launch confidential instance [default: ba5bb13f3abca960b101a759be162b229e2b7e93ecad9d1307e54de887f177ff]
--gpu / --no-gpuLaunch an instance attaching a GPU to it [default: no-gpu]
--premium / --no-premiumUse Premium GPUs (VRAM > 48GiB)
--skip-volume / --no-skip-volumeSkip prompt to attach more volumes [default: no-skip-volume]
--persistent-volumeTEXTPersistent 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-volumeTEXTEphemeral 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-volumeTEXTImmutable 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-tacAutomatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac]
--channelTEXTAleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS]
--private-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--print-message / --no-print-messagePrint the message after creation [default: no-print-message]
--verbose / --no-verboseDisplay additional information [default: verbose]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# 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

bash
aleph instance delete [OPTIONS] ITEM_HASH

Arguments

ArgumentTypeDescription
ITEM_HASHITEM HASHInstance item hash to forget

Options

OptionsTypeDescription
--reasonTEXTReason 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
--domainTEXTDomain 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-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--print-message / --no-print-messagePrint the message after deletion [default: no-print-message]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# Delete an instance
aleph instance delete ITEM_HASH

Listing Instances

List all instances associated to an account

Usage

bash
aleph instance list [OPTIONS]

Options

OptionsTypeDescription
--addressTEXTOwner address of the instances
--private-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath 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-jsonPrint as json instead of rich table [default: no-json]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# Listing your instances
aleph instance list

# Listing ADDRESS instances as json
aleph instance list --address ADDRESS --json

Rebooting an instance

Reboot an instance

Usage

bash
aleph instance reboot [OPTIONS] VM_ID
Arguments
ArgumentTypeDescription
VM_IDVM IDVM item hash to reboot

Options

OptionsTypeDescription
--domainTEXTDomain 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-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# 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

bash
aleph instance allocate [OPTIONS] VM_ID

Arguments

ArgumentTypeDescription
VM_IDVM IDVM item hash to allocate

Options

OptionsTypeDescription
--domainTEXTDomain 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-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# Allocating an instance
aleph instance allocate VM ID

Check instance logs

Retrieve the logs of an instance

Usage

bash
aleph instance logs [OPTIONS] VM_ID

Arguments

ArgumentTypeDescription
VM_IDVM IDVM item hash to retrieve the logs from

Options

OptionsTypeDescription
--domainTEXTDomain 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-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# Retrieve logs of an instance
aleph instance logs VM ID

Stop an instance

Usage

bash
aleph instance stop [OPTIONS] VM_ID

Arguments

ArgumentTypeDescription
VM_IDVM IDVM item hash to stop

Options

OptionsTypeDescription
--domainTEXTDomain 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-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# Retrieve logs of an instance
aleph instance delete VM ID

Initialize a Confidential Communication

Initialize a confidential communication session with the VM

Usage

bash
aleph instance confidential-init-session [OPTIONS] VM_ID

Arguments

ArgumentTypeDescription
VM_IDVM IDVM item hash to initialize the session for

Options

OptionsTypeDescription
--domainTEXTDomain 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
--policyINTEGERPolicy for the confidential session [default: 1]
--keep-session / --no-keep-sessionKeeping the already initiated session
--private-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# 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

bash
aleph instance confidential [OPTIONS] [VM_ID]

Arguments

ArgumentTypeDescription
VM_IDVM IDItem hash of your VM. If provided, skip the instance creation, else create a new one

Options

OptionTypeDescription
--crn-urlTEXTURL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--crn-hashTEXTHash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--policyINTEGERPolicy for the confidential session [default: 1]
--confidential-firmwareTEXTHash to UEFI Firmware to launch confidential instance [default: ba5bb13f3abca960b101a759be162b229e2b7e93ecad9d1307e54de887f177ff]
--firmware-hashTEXTHash of the UEFI Firmware content, to validate measure (ignored if path is provided) [default: 89b76b0e64fe9015084fbffdf8ac98185bafc688bfe7a0b398585c392d03c7ee]
--firmware-fileTEXTPath to the UEFI Firmware content, to validate measure (instead of the hash)
--keep-session / --no-keep-sessionFLAGKeeping the already initiated session
--vm-secretTEXTSecret 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
--nameTEXTName of your new instance
--rootfsTEXTHash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it
--compute-unitsINTEGERNumber 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
--vcpusINTEGERNumber of virtual CPUs to allocate
--memoryINTEGERMaximum memory (RAM) in MiB to allocate
--rootfs-sizeINTEGER RANGERootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125]
--timeout-secondsFLOATIf vm is not called after [timeout_seconds] it will shutdown [default: 30.0]
--ssh-pubkey-filePATHPath to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub]
--addressTEXTAddress 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-gpuFLAGLaunch an instance attaching a GPU to it [default: no-gpu]
--premium / --no-premiumFLAGUse Premium GPUs (VRAM > 48GiB)
--skip-volume / --no-skip-volumeFLAGSkip prompt to attach more volumes [default: no-skip-volume]
--persistent-volumeTEXTPersistent 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-volumeTEXTEphemeral 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-volumeTEXTImmutable 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-tacFLAGAutomatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac]
--channelTEXTAleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS]
--private-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--debug / --no-debugFLAGEnable debug logging [default: no-debug]
--helpFLAGShow this message and exit
bash
# 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

bash
aleph instance gpu [OPTIONS]

Options

OptionTypeDescription
--payment-chain[AVAX, BASE]Chain you want to use to pay for your instance
--nameTEXTName of your new instance
--rootfsTEXTHash of the rootfs to use for your instance. Defaults to Ubuntu 22. You can also create your own rootfs and pin it
--compute-unitsINTEGERNumber 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
--vcpusINTEGERNumber of virtual CPUs to allocate
--memoryINTEGERMaximum memory (RAM) in MiB to allocate
--rootfs-sizeINTEGER RANGERootfs size in MiB to allocate. Set to 0 to use default tier value and to not get prompted [x<=1953125]
--premium / --no-premiumUse Premium GPUs (VRAM > 48GiB)
--timeout-secondsFLOATIf vm is not called after [timeout_seconds] it will shutdown [default: 30.0]
--ssh-pubkey-filePATHPath to a public ssh key to be added to the instance [default: /home/$USER/.ssh/id_rsa.pub]
--addressTEXTAddress 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-hashTEXTHash of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--crn-urlTEXTURL of the CRN to deploy to (only applicable for confidential and/or Pay-As-You-Go instances)
--skip-volume / --no-skip-volumeSkip prompt to attach more volumes [default: no-skip-volume]
--persistent-volumeTEXTPersistent 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-volumeTEXTEphemeral 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-volumeTEXTImmutable 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-tacAutomatically accept the Terms & Conditions of the CRN if you read them beforehand [default: no-crn-auto-tac]
--channelTEXTAleph Cloud network channel where the message is or will be broadcasted [default: ALEPH-CLOUDSOLUTIONS]
--private-keyTEXTYour private key. Cannot be used with --private-key-file
--private-key-filePATHPath to your private key file [default: /home/$USER/.aleph-im/private-keys/ethereum.key]
--print-message / --no-print-messagePrint the message after creation [default: no-print-message]
--verbose / --no-verboseDisplay additional information [default: verbose]
--debug / --no-debugEnable debug logging [default: no-debug]
--helpShow this message and exit
bash
# 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