--- title: Cloud instances sidebar_label: cloud-instances, vpn description: "clika-cli cloud-instances, cloud-credentials, cloud-images and vpn: renting a machine in a cloud account and enrolling it as a device." --- Not every device has to be hardware you own. The platform can provision a machine in **your** cloud account, install the device agent on it, and register it as an ordinary [device](devices.md). From that point on it behaves like any other target: it takes jobs, runs benchmarks, and appears in `devices list`. Three groups cover this, in the order you use them: a credential for your cloud account, an image catalogue, and the instances themselves. `vpn` is the network side, for when an instance has to reach a private network. ## Before the first instance A cloud instance needs a stored cloud credential, and the web application is where one is added: **Settings**, then **Credentials**, choosing the provider (Azure, Google Cloud or AWS). For Azure the form takes a Tenant ID, a Client ID and Client Secret (a service principal), the Subscription ID and a Default Location, and its **Required permissions** panel names the roles the principal needs on the subscription. The platform creates and uses a resource group named `clika-cloud-`; there is no field for it. **Test** on the stored credential answers "credential validated with provider" in a few seconds. Then, on the web, **Devices**, the **Cloud helpers** tab (which shows no control until a credential exists), **Add Cloud Device**: pick the GPU class, press **Find options**, choose a type and region, and **Create**. Pick a type with more memory than the quick benchmark peaks at (a 135M-parameter model peaked above 1 GB), set the region to the credential's location yourself, and expect the first instance to create a VPN gateway that the platform keeps, and bills, until you delete it. The hourly rate shows in the CLI's JSON rather than on the configure step. ## Cloud credentials The platform needs permission to create machines in your account. That permission is stored as a cloud credential. | Command | What it does | | --- | --- | | `cloud-credentials list` | Stored credentials, with their secrets redacted. | | `cloud-credentials get ` | One credential. | | `cloud-credentials create --body ''` | Store one. | | `cloud-credentials update --body ''` | Change one. | | `cloud-credentials test ` | Check that it still works, before you find out during a provision. | | `cloud-credentials delete ` | Remove one. Organization owners and admins may remove any of the organization's credentials; a credential stored for your own user is yours to remove. | Run `cloud-credentials test` after any rotation on the cloud side. It is the difference between a clear "this credential is stale" and a provision that fails halfway. ## Images ``` clika-cli cloud-images refresh ``` The platform caches the machine images available in each region. `refresh` re-reads them from the provider, which you need after a new image is published and before it can be selected. ## Instances ``` clika-cli cloud-instances [command] ``` | Subcommand | Purpose | | --- | --- | | `catalog` | The instance types, regions and images you can provision, given your stored credentials. Read this before writing a create body. | | `list` | Instances the platform has provisioned. | | `get ` | One instance with its current state. | | `create --body ''` | Provision an instance. | | `start ` | Start a stopped instance. | | `stop ` | Stop it without destroying it, which usually stops the compute charge while keeping the disk. | | `terminate ` | Destroy it. | | `delete ` | Remove the platform's record of it. | | `retry ` | Retry a provision that failed partway. | | `refresh-post` | Re-read every instance's state from the provider. | | `refresh-post-id ` | Re-read one instance's state. | A typical first run: ``` clika-cli cloud-credentials test 5b2e0a1c-3d4e-5f60-7182-93a4b5c6d7e8 clika-cli cloud-instances catalog clika-cli cloud-instances create --body '' clika-cli cloud-instances list ``` Provisioning is asynchronous. `create` returns as soon as the request is accepted, and the instance moves through its states afterwards. Watch it with `cloud-instances get `, or with the [event feed](monitoring.md#events), which reports the device coming online once the agent registers. `stop`, `terminate` and `delete` are three different things, and the distinction costs money if you get it wrong. `stop` keeps the instance and its disk. `terminate` destroys the instance at the provider. `delete` removes the platform's record, which is what you want only after the instance is already gone. An instance in status `error` still accepts `stop`, which stops the VM's billing while you decide; to be rid of it, `terminate` it, then `delete` the record once it is gone. The web page of a failed instance offers only **Retry** and **Delete**, so stop and terminate are CLI commands. ## VPN ``` clika-cli vpn list clika-cli vpn setup --body '' clika-cli vpn verify clika-cli vpn delete ``` A VPN gateway lets provisioned instances, or devices on a private network, reach the platform and be reached by it without exposing anything publicly. `vpn verify` checks the tunnel end to end, which is worth running before you conclude a device is broken. ## Full command reference Every command below is generated from the deployment's own API description, so one subcommand is exactly one platform operation. Each entry names the method, the endpoint and the [MCP](mcp.md) tool name, so the same operation is identifiable whichever surface you drive it from. Path parameters are positional arguments, query parameters are flags, and a request body is `--body` or `--body-file`. The hand-written commands, the ones that stream, propagate an exit code, or hand your terminal to `ssh`, carry no operation line. The prose above covers the commands most people reach for. This section is the complete surface, for when you need the flag you have not used before. ### `clika-cli cloud-credentials` `cloud-credentials` has 6 subcommands. #### `clika-cli cloud-credentials create` Create cloud credential ``` clika-cli cloud-credentials create [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--body` | string | none | request body (inline JSON) | | `--body-file` | string | none | request body (path to a JSON file) | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-credentials`. MCP tool name: `post_cloud_credentials`. #### `clika-cli cloud-credentials delete` Delete cloud credential ``` clika-cli cloud-credentials delete [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `DELETE /api/cloud-credentials/{id}`. MCP tool name: `delete_cloud_credentials_id`. #### `clika-cli cloud-credentials get` Get cloud credential ``` clika-cli cloud-credentials get [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/cloud-credentials/{id}`. MCP tool name: `get_cloud_credentials_id`. #### `clika-cli cloud-credentials list` List cloud credentials ``` clika-cli cloud-credentials list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/cloud-credentials`. MCP tool name: `get_cloud_credentials`. #### `clika-cli cloud-credentials test` Test cloud credential ``` clika-cli cloud-credentials test [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-credentials/{id}/test`. MCP tool name: `post_cloud_credentials_id_test`. #### `clika-cli cloud-credentials update` Update cloud credential ``` clika-cli cloud-credentials update [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--body` | string | none | request body (inline JSON) | | `--body-file` | string | none | request body (path to a JSON file) | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `PUT /api/cloud-credentials/{id}`. MCP tool name: `put_cloud_credentials_id`. ### `clika-cli cloud-images` `cloud-images` has 1 subcommands. #### `clika-cli cloud-images refresh` Refresh cloud image cache ``` clika-cli cloud-images refresh [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-images/refresh`. MCP tool name: `post_cloud_images_refresh`. ### `clika-cli cloud-instances` `cloud-instances` has 14 subcommands. #### `clika-cli cloud-instances catalog` Get cloud instance catalog ``` clika-cli cloud-instances catalog [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--credential_id` | string | none | Cloud credential ID to use for API calls | | `--provider` | string | none | Cloud provider: aws, gcp or azure | | `--raw` | bool | `false` | print raw response without pretty-printing | | `--region` | string | none | Region to list instance types and images for | | `--zone` | string | none | Zone to list instance and accelerator types for | Endpoint: `GET /api/cloud-instances/catalog`. MCP tool name: `get_cloud_instances_catalog`. #### `clika-cli cloud-instances catalog-refresh` Refresh the cloud catalog cache ``` clika-cli cloud-instances catalog-refresh [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/catalog/refresh`. MCP tool name: `post_cloud_instances_catalog_refresh`. #### `clika-cli cloud-instances create` Provision a cloud instance ``` clika-cli cloud-instances create [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--body` | string | none | request body (inline JSON) | | `--body-file` | string | none | request body (path to a JSON file) | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances`. MCP tool name: `post_cloud_instances`. #### `clika-cli cloud-instances delete` Delete cloud instance ``` clika-cli cloud-instances delete [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `DELETE /api/cloud-instances/{id}`. MCP tool name: `delete_cloud_instances_id`. #### `clika-cli cloud-instances facets` List the accelerators and instance shapes the cloud catalog cache can offer, for a cascading form ``` clika-cli cloud-instances facets [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--backend` | string | none | Backend the engine must run on: cuda, cuda:12.4, none, rocm, decides the refusal reason and which CUDA versions are listed | | `--cuda` | string | none | Minimum CUDA version wanted (the older spelling of backend=cuda:``) | | `--gpu` | string | none | The accelerator, as the accelerator list spells it (t4, a100 80gb, rtx pro 6000) or none / cpu for no GPU; absent answers the accelerator list | | `--gpu_count` | string | none | Keep the shapes that carry at least this many GPUs | | `--min_memory_gb` | string | none | Minimum memory in GB | | `--min_vcpu` | string | none | Minimum vCPUs | | `--provider` | string | none | Keep one provider's shapes only: aws, gcp or azure | | `--raw` | bool | `false` | print raw response without pretty-printing | | `--region` | string | none | A region id keeps that region alone; any other text is a case-insensitive part of a region id or name | Endpoint: `GET /api/cloud-instances/facets`. MCP tool name: `get_cloud_instances_facets`. #### `clika-cli cloud-instances get` Get cloud instance ``` clika-cli cloud-instances get [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/cloud-instances/{id}`. MCP tool name: `get_cloud_instances_id`. #### `clika-cli cloud-instances list` List cloud instances ``` clika-cli cloud-instances list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | | `--status` | string | none | Filter by status (pending, provisioning, installing_agent, registered, running, terminating, terminated, error) | Endpoint: `GET /api/cloud-instances`. MCP tool name: `get_cloud_instances`. #### `clika-cli cloud-instances options` Find cloud instance options from a plain description ``` clika-cli cloud-instances options [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--backend` | string | none | Backend the engine must run on: cuda, cuda:12.4, cuda:13, none (CPU engine, nothing installed for the GPU), rocm (refused with a reason until the engine has it). Default: any, CUDA on an NVIDIA GPU | | `--cuda` | string | none | Minimum CUDA version wanted, e.g. 12.4 or 13 (the older spelling of backend=cuda:``; may be combined with backend=cuda, must not disagree with it) | | `--gpu` | string | none | GPU wanted, in plain words: L4, nvidia t4, A100 80GB, RTX PRO 6000, or none / cpu for a device without a GPU. A name the platform does not recognise answers 200 with an empty list and a warning saying so, never 400 | | `--gpu_count` | string | `1 when a GPU is named` | How many GPUs | | `--instance_type` | string | none | Keep one exact instance type only (case-insensitive), how a form resolves the shape a person picked into the option it launches | | `--min_memory_gb` | string | none | Minimum memory in GB | | `--min_vcpu` | string | none | Minimum vCPUs | | `--provider` | string | none | Keep one provider's machines only: aws, gcp or azure | | `--raw` | bool | `false` | print raw response without pretty-printing | | `--region` | string | none | Region preference: a region id keeps that region alone; any other text is a case-insensitive part of a region id or name (europe, korea) | Endpoint: `GET /api/cloud-instances/options`. MCP tool name: `get_cloud_instances_options`. #### `clika-cli cloud-instances refresh-post` Refresh all cloud instance statuses ``` clika-cli cloud-instances refresh-post [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/refresh`. MCP tool name: `post_cloud_instances_refresh`. #### `clika-cli cloud-instances refresh-post-id` Refresh single cloud instance status ``` clika-cli cloud-instances refresh-post-id [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/{id}/refresh`. MCP tool name: `post_cloud_instances_id_refresh`. #### `clika-cli cloud-instances retry` Retry failed cloud instance ``` clika-cli cloud-instances retry [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/{id}/retry`. MCP tool name: `post_cloud_instances_id_retry`. #### `clika-cli cloud-instances start` Start cloud instance ``` clika-cli cloud-instances start [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/{id}/start`. MCP tool name: `post_cloud_instances_id_start`. #### `clika-cli cloud-instances stop` Stop cloud instance ``` clika-cli cloud-instances stop [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/{id}/stop`. MCP tool name: `post_cloud_instances_id_stop`. #### `clika-cli cloud-instances terminate` Terminate cloud instance ``` clika-cli cloud-instances terminate [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/cloud-instances/{id}/terminate`. MCP tool name: `post_cloud_instances_id_terminate`. ### `clika-cli vpn` `vpn` has 4 subcommands. #### `clika-cli vpn delete` Delete VPN gateway ``` clika-cli vpn delete [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `DELETE /api/vpn/{id}`. MCP tool name: `delete_vpn_id`. #### `clika-cli vpn list` List VPN configs ``` clika-cli vpn list [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `GET /api/vpn`. MCP tool name: `get_vpn`. #### `clika-cli vpn setup` Setup VPN gateway ``` clika-cli vpn setup [flags] ``` | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--body` | string | none | request body (inline JSON) | | `--body-file` | string | none | request body (path to a JSON file) | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/vpn/setup`. MCP tool name: `post_vpn_setup`. #### `clika-cli vpn verify` Verify VPN connectivity ``` clika-cli vpn verify [flags] ``` Positional arguments: required ``. | Flag | Type | Default | Meaning | | --- | --- | --- | --- | | `--raw` | bool | `false` | print raw response without pretty-printing | Endpoint: `POST /api/vpn/{id}/verify`. MCP tool name: `post_vpn_id_verify`. ## Related - [Devices](devices.md): what a provisioned instance becomes once its agent registers. - [Events, metrics and alerts](monitoring.md): watching a provision complete. - [Organizations, projects and access](projects-and-orgs.md): who may store a cloud credential.