Configuration File

The Vonage Cloud Runtime Configuration file (vcr.yml), gives information to the platform on how to debug and deploy your application. It is a YAML file which has objects to allow you to configure where your instances are deployed, which Vonage application you are connected to and so on. Here is an example configuration file:

project:
    name: app
instance:
    name: dev
    runtime: nodejs22
    region: aws.use1
    application-id: 773c2b45-c20a-4d6b-8afe-24ce29ba6f92
    entrypoint: [node, index.js]
    build-script: "./build.sh"
    capabilities:
        - voice
        - messages-v1
    environment:
        - name: VONAGE_NUMBER
          value: "44700000000"
        - name: INTEGRATION_API_KEY
          secret: MY_SECRET_API_KEY
    secrets:
        - MY_SECRET_API_KEY
debug:
    name: debug
    application-id: 884c2b45-c20a-4d6b-8afe-24ce29ba6f93
    environment:
        - name: DEBUG_VONAGE_NUMBER
          value: "4471111111"
    entrypoint: [nodemon, --inspect, index.js]
    preserve-data: false

Project

A project is a namespace for grouping instances.

Name

name is a unique string identifier for your project. You can have multiple instances within a project, in a one-project-to-many instances relationship. For example, an instance for running your production code, an instance running your development code, and an instance for staging.

To have multiple instances, create a new configuration file, e.g. prod.yml, and ensure that the project name is the same. To deploy different configuration files you can pass their file paths to the deploy CLI command.

Instance

An instance is your code running on the Vonage Cloud Runtime platform. To run your code, the platform needs some information on where to run it and how to run it.

Name

name is a unique string identifier for your instance. This allows you to differentiate when you have multiple instances in your project. The name of the instance has no bearing on what environment your instance will be running, this is controlled by the region.

Runtime

runtime is the language you have built your source code with, the available options are:

  • nodejs18
  • nodejs22
  • python3
  • java21
  • ruby3.3

Region

region is where the instance will run. The currently available regions are:

  • EU - aws.euw1
  • US - aws.use1
  • APAC (Singapore) - aws.apse1
  • APAC (Sydney) - aws.apse2

Application ID

application-id is the Vonage Application ID that the instance will be connected to, this will allow Vonage Cloud Runtime to set the application's callbacks for you and access linked numbers.

Entrypoint

entrypoint is used to give commands to Vonage Cloud Runtime on how to run your application. entrypoint takes a string array which is then run to start your application. For example, to run my application I would use:

node index.js

This will become:

entrypoint: [node, index.js]

The first item is the command to be run, followed by any flags or parameters.

Build Script

build-script allows you to specify a script for VCR to run while building your application. The build script is run before your entrypoint command is called. Here is an example build script for a JavaScript and NPM project:

#!/bin/bash npm ci

Capabilities

capabilities map to the capabilities with the same name on Vonage Applications, the available options are:

  • voice
  • messages-v1
  • rtc

This allows Vonage Cloud Runtime to manage the webhooks for these capabilities. To receive the webhooks you can use the corresponding function on the Vonage Cloud Runtime SDK. See the documentation for the Voice, Messages and Conversation (RTC) providers for more information.

Environment

environment allows you to optionally pass environment variables to your application. Vonage Cloud Runtime will inject the enviroment variables for you when you run vcr debug or when your application is deployed to Vonage Cloud Runtime. So for example, VONAGE_NUMBER from above would be available as:

process.env.VONAGE_NUMBER;

Vonage Cloud Runtime also injects some environment variables by default for you. This includes things such as the Vonage Application ID and private key. For a full list, see the deploying guide.

Secrets

You can expose secrets you have created with the CLI already to the instance by adding them to the environment object as shown above. API_KEY would be available as:

process.env.API_KEY;

For more information on creating and managing secrets view the Vonage Cloud Runtime secrets guide.

Debug

The debug object gives information to the Vonage Cloud Runtime CLI on how to run your application in debug mode. For more information on debugging, view the Vonage Cloud Runtime debugging guide.

Name

name allows you to give your debugger a name so the generated debug URL is static, rather than randomized when the debugger starts.

Application ID

This allows you to specify a separate Vonage Application ID from your Instance.

Environment

This allows you to specify separate environment variables from your Instance.

Entrypoint

entrypoint for debug works the same as the instance entrypoint. This gives you the flexibility to have a separate debug workflow for example including a file watcher to restart the application when changes are made:

nodemon --inspect index.js

Becomes:

entrypoint: [nodemon, --inspect, index.js]

Preserve Data

preserve-data allows you to keep data stored with Instance State between runs of the debugger. It is false by default.