Migrating Services to Riven

Install the CLI

Install the Riven CLI, which handles proto codegen, service scaffolding, Docker publishing, and deployments:

curl -fsSL https://docs.riven-ai.dev/api/install | bash

Verify the installation:

riven --cli-version

Authenticate

Log in to the platform to get an auth token:

riven auth login

This opens a browser window for authentication. Your token is stored in ~/.config/riven/credentials.json.

Initialize your workspace

Set up the workspace configuration with your organization and proto registry:

riven init --registry-url https://proto.riven-ai.dev --org-id <your-org-id>

This creates a .rivenrc.json file in your project root with registry URL, org ID, and default settings.

Define your Proto API

Create your service's API contract using Protocol Buffers. This is the source of truth for all service communication.

Create a proto/ directory and define your service:

syntax = "proto3";
 
package riven.myservice.v1;
 
service MyService {
  rpc GetItem(GetItemRequest) returns (GetItemResponse) {}
  rpc ListItems(ListItemsRequest) returns (ListItemsResponse) {}
  rpc CreateItem(CreateItemRequest) returns (CreateItemResponse) {}
}
 
message GetItemRequest {
  string id = 1;
}
 
message GetItemResponse {
  Item item = 1;
}
 
message Item {
  string id = 1;
  string name = 2;
  string description = 3;
}
 
// ... remaining message types

Lint your proto files to catch issues early:

riven proto lint

Generate code

Run codegen to produce TypeScript (or Python) client and server stubs from your proto definitions:

riven proto generate

Generated code is placed in src/__generated__/ and should be committed to your repository. It is excluded from linting and test coverage.

Scaffold the service

Use the CLI to generate the service boilerplate, including Connect RPC server setup, health checks, and Prisma schema:

riven service create my-service --lang node

This generates:

• src/index.ts — Service entry point with Connect RPC server
• src/service.ts — Service implementation skeleton
• prisma/schema.prisma — Database schema (PostgreSQL)
• Dockerfile — Multi-stage production build
• package.json — Dependencies and scripts

For Python services:

riven service create my-service --lang python

Implement business logic

Fill in the service implementation. The scaffolded code provides the RPC handlers as empty methods — implement each one:

import type { MyService } from './__generated__/riven/myservice/v1/my_service_connect';
 
export const myServiceImpl: MyService = {
  async getItem(request) {
    const item = await prisma.item.findUnique({
      where: { id: request.id },
    });
    if (!item) {
      throw new ConnectError('Item not found', Code.NotFound);
    }
    return { item };
  },
 
  async listItems(request) {
    const items = await prisma.item.findMany();
    return { items };
  },
 
  async createItem(request) {
    const item = await prisma.item.create({
      data: { name: request.name, description: request.description },
    });
    return { item };
  },
};

Write tests alongside your implementation:

yarn test

Build the Docker image

The scaffolded Dockerfile uses a multi-stage build. Build and tag following the required format:

# Get the version and short SHA
VERSION=$(node -p "require('./package.json').version")
SHA=$(git rev-parse --short HEAD)
TAG="${VERSION}-${SHA}"
 
# Build the image
docker build -t my-service:${TAG} .

Or use the CLI to build and push in one step (next step).

Publish the image

Push the image to the ECR registry:

riven publish

This command:

1. Reads the version from package.json
2. Appends the short git SHA
3. Builds the Docker image
4. Pushes to the configured ECR repository

Deploy to the platform

Deploy your service to the Riven platform:

riven dev-center service deploy my-service \
  --tag ${TAG} \
  --repo-type js \
  --image-repository <account-id>.dkr.ecr.us-east-1.amazonaws.com/my-service

For subsequent deployments of an already-registered service:

riven dev-center rollout start my-service ${TAG}

Verify the deployment

Check that your service is running and healthy:

# Check rollout status
riven dev-center rollout status my-service
 
# View pod logs
riven dev-center logs my-service
 
# Run diagnostics
riven doctor

Your service is now live on the platform and accessible via Connect RPC through the platform gateway.