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.
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.
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.