Getting started with the Oyster CLI

Oyster
,
1

Getting Started with Oyster CVM CLI: Your Gateway to Trusted Execution Environments

Are you a developer looking to leverage the power of Trusted Execution Environments (TEEs) in your applications? Look no further! Oyster CVM CLI provides a simple yet powerful interface to deploy, manage, and monitor your applications in secure CVMs on the Marlin network. In this guide, we’ll walk through the essential commands to get you up and running with Oyster CVMs(Confidential Virtual Machines).

Prerequisites

Before diving in, make sure you have:

  • The Oyster CVM CLI installed (refer this article or if you have rust setup in your system you can directly build from source)

  • A wallet with some funds for deployment (on Arbitrum One Network)

Getting Started

1. Prepare Your Docker Compose File

First, let’s create a simple Docker Compose file for your application. Create a docker-compose.yml file with the following content:


services:

  redis:
  
    image: redis:latest
    
    command: ["redis-server"]
    
    network_mode: "host"
  
  redis-cli:
  
    image: redis:latest
    
    command: ["sh", "-c", "while true; do redis-cli -h localhost ping; sleep 5; done"]
    
    network_mode: "host"

This is a minimal example, but you can replace it with your own application. The key is to define your services in the standard Docker Compose format.

You can build and publish your custom images to docker hub and just use them the same way you import any standard docker image like redis as shown above.

Note: The network mode must be set to ‘host’ for proper functionality.

2. Deploy Your Application

Now, let’s deploy this application to an Oyster CVM. The deploy command is your entry point to launching applications on Oyster:


oyster-cvm deploy \

--duration-in-minutes 60 \

--docker-compose ./docker-compose.yml \

--wallet-private-key <YOUR_PRIVATE_KEY>

Let’s break down this command:

  • --duration-in-minutes 60: Sets the deployment duration to 60 minutes

  • --docker-compose: Specify the path to your docker-compose file here.

You can also specify other args but there are default values populated if not passed. Eg. by default:

  • --arch arm64: Specifies the architecture to use

  • --preset blue: Specifies the base image to use

  • --region ap-south-1: Specifies the region for deployment

  • --instance-type c6g.large: Specifies the instance type on which the image will be deployed [c6g.large for arm64 & c6a.xlarge for amd64 based images]

The command will:

  1. Parse your Docker Compose file

  2. Calculate the required resources and associated costs for the duration

  3. Deploy your application to the CVM

  4. Return a txn hash, job ID and IP address for your deployed application

Note: The cli waits for 3 mins before it starts to poll the control plane for the IP, as it usually takes some time to spin up your app in the CVM.

3. Deploy in debug mode and stream logs


oyster-cvm deploy \

--duration-in-minutes 60 \

--docker-compose ./docker-compose.yml \

--wallet-private-key <YOUR_PRIVATE_KEY> \

--debug

Once your application is deployed in debug mode, it will attach to the console and start streaming logs as soon as the CVM starts.

Alternatively you can pass --no-stream arg along with the deploy command if you don’t want to print logs immediately.

Later at any point, to access logs for any given CVM running in debug mode, use:


oyster-cvm logs --ip <CVM_IP_ADDRESS> --start-from <LOG_ID>

This will establish a connection to your CVM and stream logs in real-time. If you’d like to start streaming from a specific point, use the --start-from flag.

Pro Tip: Set LOG_ID as 0 to print from the beginning.

4. List Your Active Deployments

Need to check on all your deployments? The list command provides a quick overview:


oyster-cvm list --address <YOUR_WALLET_ADDRESS>

This will show all active jobs associated with your wallet address, including:

  • Job ID

  • Hourly rate

  • Current balance

  • Estimated time remaining

  • Provider information

5. Verify CVM Attestation

One of the most powerful features of TEEs is their attestation capability, which provides cryptographic proof that your code is running in a secure CVM with the expected configuration. The verify command allows you to check the attestation of your CVM:


oyster-cvm verify --enclave-ip <CVM_IP_ADDRESS> --pcr-preset "base/blue/v1.0.0/arm64"

Where:

--pcr-preset: specifies the pcrs of the blue image used in the deployment

This command:

  1. Connects to the attestation endpoint of your CVM

  2. Retrieves the attestation document

  3. Verifies the document’s authenticity using the AWS Nitro root key

  4. Checks PCR values (Platform Configuration Registers) returned from the Oyster CVM to ensure the CVM has not been tampered with

  5. Displays public key information for the CVM

Verification ensures that your application is running in a genuine, untampered CVM, providing the security guarantees you need for sensitive workloads.

6. Deposit Funds to a Job

If you need to extend the runtime of your deployment without stopping it, you can add more funds using the deposit command:


oyster-cvm deposit --job-id <JOB_ID> \

--amount <AMOUNT_IN_USDC_UNITS> \

--wallet-private-key <YOUR_PRIVATE_KEY>

Note that USDC has 6 decimal places, so to deposit 1 USDC, you would use --amount 1000000.

The deposit process:

  1. Verifies the job exists

  2. Approves the USDC transfer (interacting with the USDC token contract)

  3. Calls the jobDeposit function on the Oyster market contract

  4. Confirms the successful deposit

The added funds will extend the runtime of your deployment proportionally to the hourly rate. For example, if your job costs 1 USDC per hour and you deposit 2 USDC, you’ve added 2 hours of runtime.

7. Withdraw Funds from a Job

If you no longer need all the funds allocated to a job, you can withdraw the unused portion:


oyster-cvm withdraw --job-id <JOB_ID> \

--amount <AMOUNT_IN_USDC_UNITS> \

--wallet-private-key <YOUR_PRIVATE_KEY>

To withdraw all available funds, use the --max flag instead of specifying an amount:


oyster-cvm withdraw --job-id <JOB_ID> \

--max \

--wallet-private-key <YOUR_PRIVATE_KEY>

The withdrawal process:

  1. Calculates the current balance, accounting for time elapsed since the last settlement

  2. Ensures you’re leaving enough funds for a buffer period (approximately 7 minutes of runtime)

  3. Initiates the withdrawal transaction

  4. Returns the unused funds to your wallet

This feature is particularly useful if you’ve overestimated your needs or if you’re finished with a deployment but still have a significant amount of funds remaining.

8. Update Job Parameters

You can modify certain parameters of a running job using the update command:


oyster-cvm update --job-id <JOB_ID> \

--wallet-private-key <YOUR_PRIVATE_KEY>

Available update options include:

  • --image-url <NEW_IMAGE_URL>: Change the CVM image URL

  • --debug <true|false>: Enable or disable debug mode

For example, to enable debug mode on an existing deployment:


oyster-cvm update --job-id <JOB_ID> \

--debug true \

--wallet-private-key <YOUR_PRIVATE_KEY>

9. Stop a Deployment

When you’re finished with a deployment, you can stop it to avoid unnecessary costs:


oyster-cvm stop --job-id <JOB_ID> \

--wallet-private-key <YOUR_PRIVATE_KEY>

This will gracefully terminate your deployment and stop any further charges.

Best Practices

  1. Use Descriptive Job Names: Add --job-name to your deploy command for easier identification

  2. Debug Mode: For testing purposes, add --debug to your deploy command, as it allows you to access logs.

  3. Verify Attestations: For security-critical applications, always verify the CVM attestation

  4. Fund Management: Deposit additional funds before you run out to avoid interruptions

  5. Resource Planning: Choose appropriate instance types for your workload and regions based on the demographic

Conclusion

Oyster CLI provides a streamlined interface for deploying applications in secure CVMs on the Marlin network. By following this guide, you now have the essential knowledge to deploy, monitor, and manage your applications using Oyster.

Happy computing in your secure CVMs!