Spheron Protocol CLI

Explore detailed steps and options of the Spheron Protocol CLI. In this guide we will define each environment variable and use within each command.

Install Spheron Protocol CLI (Linux, MacOS)

Prerequisites

To install Spheron Protocol CLI using script, make sure you have curl (opens in a new tab) installed on your system. To check, quickly:

curl --version

Install Spheron Protocol CLI

To install the Spheron Protocol CLI on the system, just run this one command in your terminal and pass the password during the prompt:

curl -sL1 https://sphnctl.sh | bash

Verify Spheron Installation

# Verify the installation by using a simple command to check the Spheron version
sphnctl -h

Wallet Configurations

Creating a Wallet

To create a new wallet, start by configuring the name of your key. Run the command below, replacing [wallet name] with a name of your choice:

sphnctl wallet create --name [Wallet Name]

Here is an example of how the result will look:

Created account xxx:
 path: /Users/mitrasish-personal/.spheron/xxxxxyx.json
 address: 0x5C2432F3cB41927212e46e7224036d78eF3F2A93
 secret: xxxxxxxxxx
 mnemonic: xxxxxx xxxxx xxxx xxxxx xxxxx xxxx xxxxx xxxxx

Make sure to read the output carefully and save your mnemonic phrase and key secret in a secure location.

Once created, the wallet will be saved locally at ~/.spheron. You can access the key-secret of the current wallet in ~/.spheron/config.json. The newly created wallet will automatically be set as the current wallet. If needed, you can change the wallet by following the instructions in the "Changing Your Wallet" section.

Wallet Balance

You can check the current balance the wallets you created in local:

sphnctl wallet balance

Here is an example of how the result will look:

Current ETH balance: [Balance]

Checking the Current Wallet

To see which wallet is currently in use for deployments, run the following command:

sphnctl wallet current

Here is an example of how the result will look:

Currently using account xxx:
	path: /Users/mitrasish-personal/.spheron/abc.json
	address: 0x2c11A76298A111B8cAASCCS205dc8f0A268ASCS
	passphrase: testPaxxxx

Changing Your Wallet

If you need to switch to a different wallet, use the command below, providing the name and the key-secret of the new wallet:

sphnctl wallet use --name [Wallet Name] --key-secret [Key Secret]

Here is an example of how the result will look:

Switched default account to xxx:
	path: /Users/mitrasish-personal/.spheron/acbv.json
	address: 0x2c11A76298A111B8cAAvvvvvv05dc8f0A268ASCS
	passphrase: test

This will update the current wallet to the specified one.

Export the Private Key of Wallet

You can export your private key of the wallets you created in local and import it in metamask:

sphnctl wallet private-key

Here is an example of how the result will look:

Here is the private key of the wallet [address]:
[Exported Private Key]

Escrow Account Overview

You need to fund your wallet with some ETH to deploy anything on Spheron. We are currently deployed on Arbitrum chain, you can try getting some ETH from the faucet or buy it from the market to pay for the transaction fees.

Depositing Fund

You need to deposit some minimum balance of any token to your account before doing any deployment. Any deployment on Spheron need user to deposit some amount of token that is used for the deployment otherwise the deployment will not start. To deposit a specific token like USDT, you need to run this command:

sphnctl payment deposit --amount [Amount] --token [Token Name]

Here is an example of how the result will look:

Successfully deposited [Amount] [Token Name]! Start deploying!!!
Tx hash: https://arbiscan.io/tx/0xc33a13a0e5e07ca54fea6077f7d14052ac65cf36682983cc69eed16a162ab1f1

The amount you pass need to be in full precision i.e if the USDT has 6 precision then the amount of 1 USDT will be 1000000.

Note: Precision is crucial for any deployment on Spheron. All token values passed in ICL or CLI must have the correct precision. For details on token precision, refer to the Supported Payment Token section.

Note: There is a restriction on minimum amount of deposited funds in your account of any token to start any deployment. Refer Supported Payment Tokens to see the minimum token requirement for deposit.

Withdrawing Fund

To withdraw a specific token, you need to run this command:

sphnctl payment withdraw --amount [Amount] --token [Token Name]

Here is an example of how the result will look:

Successfully withdrawn [Amount] [Token Name]! 
Tx hash: https://arbiscan.io/tx/0xc33a13a0e5e07ca54fea6077f7d14052ac65cf36682983cc69eed16a162ab1f1
 
If you want to deposit some other token, Please do this:
sphnctl payment deposit --amount [Amount] --token [Token Name]

The amount you pass need to be in full precision i.e if the USDT has 6 precision then the amount of 1 USDT will be 1000000.

Checking your Escrow Balance

Check your account has sufficient balance by running:

sphnctl wallet balance --token [Token Name]

Here is an example of how the result will look:

This is your current balance for this token [Token Name]:
 Total: 443064994100000000
 
Deposited USDT balance
 Unlocked: 22929459
 Locked: 4164

Listing All the Payment Tokens

To find all the payment tokens that are registered in Spheron Protocol, you need to run this command to fetch them:

sphnctl payment tokens

Here is an example of how the result will look:

Available tokens:
Token: ETH, Precision: 18, TokenAddress: 0x0000000000000000000000000000000000000000
Token: USDT, Precision: 6, TokenAddress: 0x24A05B480235Ccb450bf7Ce7e9F65072Ed732292

Create your Configuration

Create a deployment configuration gpu.yaml to deploy the jupyter/minimal-notebook for Jupyter Notebook container using ICL.

You may use the sample deployment file as-is or modify it for your own needs as described in our ICL (Infrastructure Composition Language) documentation. A typical modification would be to reference your own image instead of our image.

EXAMPLE CONFIGURATION:

cat > gpu.yml <<EOF
---
version: "1.0"
 
services:
  web:
    image: jupyter/minimal-notebook:latest
    expose:
      - port: 8888
        as: 8888
        to:
          - global: true
    env:
      - TEST=test
profiles:
  name: hello-world
  mode: provider
  duration: 2min
  tier:
    - community
  compute:
    web:
      resources:
        cpu:
          units: 0.5
        memory:
          size: 1Gi
        storage:
          size: 1Gi
  placement:
    westcoast:
      attributes:
        region: us-east
      pricing:
        web:
          denom: USDT
          amount: 500000
deployment:
  web:
    westcoast:
      profile: web
      count: 1
EOF

Deployment Overview

Create your Deployment

To deploy on Spheron, run:

sphnctl deployment create gpu.yml

Here is an example of how the result will look:

Checking ballance for wallet: 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
Validating SDL configuration.
SDL validated.
Sending configuration for provider matching.
Create deployment tx: [Tx Hash]
Waiting for providers to bid on the deployment order...
Bid found.
Order matched successfully.
Deployment created using wallet 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
 lid: 44
 provider: 0x6634d41cccBD1E1576Ed4c6226832521A66bF874
 agreed price: 158747943694
Sending the manifest for deployment…
Deployment manifest sent, waiting for acknowledgment.
Deployment is finished.

The lid that we get from the deployment is called Lease ID. This is the identifier that you need to use to access your deployment’s logs, and status.

Fetch Deployment Details

To fetch your deployment / lease details, you need to run this command to fetch it:

This will contain URL to access the deployment server, all the assigned ports and the URI to access it. With this you can check your deployment status.

sphnctl deployment get --lid [Lease ID]

Here is an example of how the result will look:

Status of the deployment ID: [Lease ID]
Deployment details:
 Status:  Matched
 Provider:  avaaaa
 Price:  1.21222
 Start time:  2024-07-25T10:10:12Z
 
Services running:
  web
    URL: []
    Ports:
      - provider.provider.devnetasphn.com:42100 -> 8888 (TCP)
    Replicas: 1/1 available, 1 ready
    Host URI: provider.devnetasphn.com
    Region: us-east
    IPs: []

Fetch Deployment Logs

To fetch your deployment's logs, you need to run this command to fetch it:

sphnctl deployment logs --lid [Lease ID]

Here is an example of how the result will look:

Here is the logs for the Lease ID: 101

[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Entered start.sh with args: jupyter lab
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Running hooks in: /usr/local/bin/start-notebook.d as uid: 1000 gid: 100
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Done running hooks in: /usr/local/bin/start-notebook.d
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Running hooks in: /usr/local/bin/before-notebook.d as uid: 1000 gid: 100
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Done running hooks in: /usr/local/bin/before-notebook.d
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] Executing the command: jupyter lab
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [I 2024-07-02 15:19:39.753 ServerApp] Package jupyterlab took 0.0000s to import
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [I 2024-07-02 15:19:39.776 ServerApp] Package jupyter_lsp took 0.0222s to import
[0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8/46/1/1/0x6634d41cccBD1E1576Ed4c6226832521A66bF874][web-65cc59bb99-bq78t] [W 2024-07-02 15:19:39.776 ServerApp] A _jupyter_server_extension_points function was not found in jupyter_lsp. Instead, a _jupyter_server_extension_paths function was found and will be used for now. This function name will be deprecated in future releases of Jupyter Server.
...

There are some other options that you can use to stream logs or change output format, etc.

Other Options:

Option	Default	Description
`-f, --follow`		Follow log output
`-o, --output`	'text'	Output format `text
`-t, --tail`	`all`	The number of lines from the end of the logs to show. Defaults to `all`.
`--service`	No	Name of service you want specifically query the logs from.

Fetch Deployment Events

To fetch your deployment's events, you need to run this command to fetch it:

sphnctl deployment events --lid [Lease ID]

Here is an example of how the result will look:

Here is the logs for the Lease ID: 101
 
{
  "type": "Normal",
  "reportingController": "default-scheduler",
  "reportingInstance": "default-scheduler-provider.devnetasphn.com",
  "reason": "Scheduled",
  "note": "Successfully assigned 48qqj898n07hat4i3gkjfufcnpmej2hssi2hd0tjk7ua6/web-65cc59bb99-bq78t to spheron-node2",
  "object": {
    "kind": "Pod",
    "namespace": "48qqj898n07hat4i3gkjfufcnpmej2hssi2hd0tjk7ua6",
    "name": "web-65cc59bb99-bq78t"
  },
  "lease_id": {
    "owner": "0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8",
    "dseq": 46,
    "gseq": 1,
    "oseq": 1,
    "provider": "0x6634d41cccBD1E1576Ed4c6226832521A66bF874"
  }
}
{
  "type": "Normal",
  "reportingController": "kubelet",
  "reportingInstance": "spheron-node2",
  "reason": "Pulled",
  "note": "Container image \"jupyter/minimal-notebook:latest\" already present on machine",
  "object": {
    "kind": "Pod",
    "namespace": "48qqj898n07hat4i3gkjfufcnpmej2hssi2hd0tjk7ua6",
    "name": "web-65cc59bb99-bq78t"
  },
  "lease_id": {
    "owner": "0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8",
    "dseq": 46,
    "gseq": 1,
    "oseq": 1,
    "provider": "0x6634d41cccBD1E1576Ed4c6226832521A66bF874"
  }
}
....

There are some other options that you can use to stream events or change output format, etc.

Other Options:

Option	Default	Description
`-f, --follow`		Follow log output
`-t, --tail`	'all'	The number of lines from the end of the logs to show. Defaults to 'all'.
`--service`	No	Name of service you want specifically query the logs from.

Connect to Deployment Shell

To connect to your deployment's shell access, you need to run this command to fetch it:

sphnctl deployment shell [Service_Name] [Command] --lid [Lease ID] --stdin --tty

This will create a shell access to the service running on the instance. The service name can be found in the ICL yaml under services parameter.

Arguments:

Service Name: This is the name defined for your service in your ICL YAML file under the services parameter. You can connect to any service running in the deployment by specifying the service name in the shell command.
Command: This is the command you want to execute within the service of the deployment, such as /bin/sh.

NOTE: If the service name or command you need to pass contains spaces, enclose the entire string in quotes. This ensures it is treated as a single argument.

Other Options:

Option	Mandatory	Description
`--lid`	Yes	Lease ID of the deployment
`--stdin`	No	Connect stdin connection to the service
`--tty`	No	Connect an interactive terminal to the deployment. If not passed, it will only log the result of the command sent.
`--replica-index`	No	Replica index of the service in the instance to connect to if there are multiple of them otherwise not needed.

Update the Deployment

Update the deploy.yml manifest file with the desired change.

NOTE: Not all attributes of the manifest file are eligible for deployment update. If the ports are changed, a re-deployment of the workload is necessary. Other attributes, such as specs, deployment image and environment, are eligible for updates.

sphnctl deployment update --lid [Lease ID] gpu.yml

Here is an example of how the result will look:

Checking ballance for wallet: 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
Validating SDL configuration.
SDL validated.
Sending update request...
Update request sent: [Tx Hash]
Waiting for providers to accept on the update order...
Update request accepted by the provider.
Deployment update using wallet 0x2c11A76298A111B8cA8Db82205dc8f0A2688e6e8
 lid: 26
 provider: 0xe5CF265769039267c8FDbadd87f8a28B99769267
 agreed price: 125304312995
Sending the manifest for update…
Deployment manifest sent, waiting for acknowledgment.
Update deployment is finished.

NOTE:

If you want to change the compute resources, a new agreed price will be provided by the provider. Please note that if the requested compute resources are not available, the provider can choose not to accept the update request. In that case, you can close the deployment and create a new one.
There are some restrictions on what can be updated:
- Ports cannot be updated at runtime
- Region cannot be updated at runtime
- Tier cannot be updated at runtime
- Token cannot be updated at runtime

Close Deployment

Should you need to close the deployment follow this step.

sphnctl deployment close --lid [Lease ID]

Here is an example of how the result will look:

Close request sent to provider: [Tx Hash]

Get all the Deployment

If you want to fetch all the leases you deployed till now using your current wallet.

sphnctl deployment list

Here is an example of how the result will look:

   ID|                                    Provider|   State|             StartTime|
  171|  0xb99E315d14653A7e2068b2764289e6F61755ebce|  Active|  2024-07-25T09:51:41Z|

NOTE: You can add -a flag to filter all the active leases on your wallet. Also note that if you change you wallet, all the leases will be different from what you used to see.

Infrastructure Composition Language Supported Configurations