Custom Runtimes

Custom runtimes allow you to install dependencies for use in your Python and JavaScript code. After building a custom runtime, you can use it with the Execute Code endpoint.

You can create custom runtimes from the Riza Dashboard, but in this guide, we’ll use the Custom Runtimes API to programmatically create and manage custom runtimes.

​

Set up

Before getting started, you’ll need an API key from the Riza Dashboard. Export it as an environment variable within your shell:

export RIZA_API_KEY=<your-api-key>

​

Create a Python custom runtime

In this example, we’ll create a custom Riza runtime environment with the Markdown Python package, which converts Markdown to HTML.

The required parameters are “name”, “language” and “manifest_file”, which is a simple PyPi requirements file declaring your dependencies.

import Riza from "@riza-io/api";

const riza = new Riza();

async function main() {
  const resp = await riza.runtimes.create({
    name: "acme_corp_custom_runtime",
    language: "python",
    manifest_file: {
      name: "requirements.txt",
      contents: "markdown==3.7",
    },
  });
  console.log(resp);
}

main();

The resulting runtime object you receive from the API will look like this. Take note of the id and revision_id parameters, which we’ll use in future steps.

{
	'id': '01JFESTGXM...',
	'language': 'python',
	'name': 'acme_corp_custom_runtime',
	'revision_id': '01JFETP2VD...',
	'status': 'pending',
	'additional_python_imports': '',
	'manifest_file': ManifestFile(contents='markdown==3.7', name='requirements.txt')
}

Each custom runtime will have one or more associated revisions. The first revision is automatically created when you create a runtime. You’ll have a new revision_id each time you update your dependencies, while the runtime id will remain the same.

​

Create a JavaScript custom runtime

In this example, we’ll create a custom Riza JavaScript runtime environment with the marked package.

import Riza from "@riza-io/api";

const riza = new Riza();

async function main() {
  const resp = await riza.runtimes.create({
    name: "acme_corp_custom_runtime",
    language: "javascript",
    manifest_file: {
      name: "package.json",
      contents: '{"dependencies": {"marked": "^15.0.6"}}',
    },
  });
  console.log(resp);
}

main();

​

Wait for the custom runtime to build

Building a custom runtime is not instant. It will likely take a few minutes.

To check a build’s status, use the Riza API to fetch the custom runtime. The runtime object’s status parameter indicates whether the latest build is complete and whether it succeeded or failed.

To monitor progress, periodically call the API until the status is either "succeeded" or "failed". The code below demonstrates this approach.

import Riza from "@riza-io/api";

const riza = new Riza();

async function pollRuntimeStatus(runtimeId) {
  const pollingIntervalSeconds = 2000;

  while (true) {
    const resp = await riza.runtimes.get(runtimeId);
    console.log(resp.status);

    if (resp.status === "succeeded" || resp.status === "failed") {
      return resp.status;
    }

    await new Promise((resolve) => setTimeout(resolve, pollingIntervalSeconds));
  }
}

const finalStatus = await pollRuntimeStatus("01JFESTGXM..."); // runtime `id` from previous step
console.log(`Final status: ${finalStatus}`);

​

Use the custom runtime

If the custom runtime build succeeds, you can now use it to run code that imports the Markdown package.

You’ll need the runtime revision ID from the first step to use the runtime with the Execute Code endpoint.

Now, you can execute Python code with the markdown package using the custom runtime from the previous step.

import Riza from "@riza-io/api";

const pythonCode = `
import sys
import markdown

print(markdown.markdown(sys.stdin.read()))
`;

const riza = new Riza();

async function main() {
  const resp = await riza.command.exec({
    runtime_revision_id: "01JFETP2VD...",
    code: pythonCode,
    stdin: "**Hello, Markdown!**",
  });
  console.log(resp);
}

main();

Similarly, you can execute JavaScript code with the marked package using the custom runtime from the previous step.

import Riza from "@riza-io/api";

const jsCode = `
import { marked } from 'marked'

const input = await new Response(process.stdin).text();

console.log(marked(input));
`;

const riza = new Riza();

async function main() {
  const resp = await riza.command.exec({
    runtime_revision_id: "01JFETP2VD...",
    code: jsCode,
    stdin: "**Hello, Markdown!**",
  });
  console.log(resp);
}

main();

​

Next steps

Check out the Create Runtime Revision endpoint if you need to add or remove dependencies.

If you have questions, please drop us a line in Discord.