
How to build a generative media integration with Codex
Summary
Codex can build, debug and maintain a video, image, audio or real-time avatar generation integration end to end.
Install the Runway Dev plugin and Codex gets the Runway Dev MCP, which reads your Runway Dev account and the live model catalog, plus seven Runway Dev skills for building with the API.
You can also connect the Runway Dev MCP and install the skills yourself from the terminal.
This article covers the plugin install, sign-in, your API key and the first build.
With the plugin installed, Codex picks models against current prices and input limits, configures whatever the integration needs and reads back the actual cause when a generation fails.
Step 1: Install the Runway Dev plugin in Codex
Run these commands in a terminal:
codex plugin marketplace add runwayml/skills
codex plugin add runway-api@runway-dev
codex mcp login runway-dev
The first command adds Runway Dev’s plugin marketplace from the runwayml/skills repository, the second installs the plugin and the last opens your browser to sign in to your Runway Dev account. Start a new Codex session to use the plugin. The Runway Dev plugin guide keeps the current commands.
Runway Dev is also in the plugin directory that ChatGPT and Codex share. To install from there instead, open Runway Dev in the plugin directory, search for it in the Plugins tab of the Codex app or enter /plugins in Codex CLI. Install from one place only, so Codex loads one copy of the skills. Plugins run in Codex CLI and the Codex app; the IDE extension takes the MCP and skills route below.
The Runway Dev plugin bundles two parts:
- The Runway Dev MCP, at
https://dev.runwayml.com/mcp. It lets Codex read the projects on your account, the models each one can call with their prices and input limits, your credit balance, your Model Routers, your Characters and the record behind any task. - Seven Runway Dev skills:
runway-dev-setup,runway-dev,runway-dev-models,runway-dev-model-routers,runway-dev-characters,runway-dev-recipesandrunway-dev-workflows. They show Codex how to integrate the API with the official SDKs before it writes anything.
Complete the sign-in yourself rather than asking Codex to automate it. No API key goes into the plugin or config.toml: the connection is OAuth, and your keys stay in your Runway Dev account.
Confirm it worked. Ask which Runway Dev account it is connected to and how many credits you have. It should return the email on your Runway Dev account and your current balance.
If you’re using the Codex app: start from Quickstart
Open Quickstart in Runway Dev and click Open in Codex. It opens a new thread carrying a prompt that points at Runway Dev’s setup brief, and the agent works from there: it inspects your project, reads the documentation and runs the plugin install commands itself. Approve the sign-in in your browser when it asks.
That button is an app deep link, so it only works if you have the Codex app. From the terminal, use the commands above, or use Copy prompt in Quickstart and paste it into Codex.
Or connect the Runway Dev MCP and the skills yourself
The same two parts can be set up one at a time, which is also the route for the Codex IDE extension. Use one route only: with the plugin installed, this would give Codex a second copy of each.
codex mcp add runway-dev-mcp --url https://dev.runwayml.com/mcp
codex mcp login runway-dev-mcp
npx skills add runwayml/skills --skill runway-dev-setup --skill runway-dev --skill runway-dev-models -a codex -y
You can also declare the server in ~/.codex/config.toml instead of using codex mcp add, as the Runway Dev MCP setup guide describes, then run the same login command:
[mcp_servers.runway-dev-mcp]
url = "https://dev.runwayml.com/mcp"
Add the skill for what you are building: runway-dev-models, runway-dev-model-routers, runway-dev-characters, runway-dev-recipes or runway-dev-workflows. runway-dev-setup and runway-dev come along every time.
If you’re using ChatGPT rather than Codex
ChatGPT installs the same Runway Dev plugin from the shared plugin directory. That is useful for asking about your account, your models and your tasks in conversation, and How to connect ChatGPT to Runway Dev has the steps. Codex is the surface that works inside your codebase, so use Codex for the integration and ChatGPT for the questions.
Step 2: Add your API key to the project
The MCP connection is OAuth, but a live generation call still needs a key of its own. The first time Codex is ready to run something, it asks for RUNWAYML_API_SECRET in the project environment.
Create the key in your Runway Dev account and add it to the project’s environment file yourself. Do not paste it into the thread, and do not let it end up hardcoded: Codex reads it from the environment.
Step 3: Describe what you are building
Codex now has your codebase, your account and the live catalog, so it does not need to be told which endpoint to call. It needs to know what you are building.
- Say what someone using your product should be able to do.
- Name what you already have as input: a product photo for image to video, a script for text to video, a catalog feed.
- Name what you need out: duration, resolution, format, whether it needs audio.
- Say where it runs: a route in your web app, a background job, a nightly batch.
- Give your constraints: a ceiling per generation, how long a user will wait, the quality bar you are holding.
- Ask it to explain which Runway Dev surface it plans to use, and why, before it writes any code.
Runway Dev offers more than a generation endpoint, and the right surface depends on the job:
- A Model Router, when you want the best model for each request without evaluating models yourself. Your code passes a config ID instead of a model name, and Codex can create the router and rewrite the calling code in the same turn.
- A Recipe, when Runway has already built and tuned the use case. One call returns a production-ready asset, with the model selection, prompting and chaining already done.
- A custom Workflow, when the pipeline is specific to you and takes several steps. It is built visually in the Runway Creative App, then published as an endpoint your integration calls once.
- A model called directly, when you already know which one you want.
When a generation fails, Codex looks the task up itself and reads the actual cause, whether that is a moderation rejection, an asset over a size limit or a malformed request body, rather than working backwards from a status code.
You are now ready to let Codex handle media generation with Runway Dev autonomously, end to end.
Install the Runway Dev plugin in Codex and describe your first feature. Create an account to start building.
FAQ
How do I connect Codex to Runway Dev?
Install the Runway Dev plugin: run codex plugin marketplace add runwayml/skills, then codex plugin add runway-api@runway-dev, then codex mcp login runway-dev to sign in to your Runway Dev account in the browser. Start a new Codex session to use it.
What does the Runway Dev plugin for Codex include?
The Runway Dev MCP at https://dev.runwayml.com/mcp, which reads your Runway Dev account and the live model catalog, and seven Runway Dev skills covering setup, the SDKs, models, Model Routers, Characters, Recipes and Workflows.
Can I install the Runway Dev plugin from the Codex plugin directory?
Yes. Enter /plugins in Codex CLI or open the Plugins tab in the Codex app, search for Runway Dev and install it. It is the same plugin the terminal commands install, so install it from one place only.
Can I add Runway Dev MCP to config.toml instead of using the CLI?
Yes. Add an [mcp_servers.runway-dev-mcp] block in ~/.codex/config.toml with url = "https://dev.runwayml.com/mcp", then run codex mcp login runway-dev-mcp to complete the browser sign-in. Install the skills with npx skills add alongside it, or use the Runway Dev plugin, which sets up both.
How do I connect Runway Dev to the Codex app?
Install the Runway Dev plugin from the Plugins tab, or open Quickstart in Runway Dev and click Open in Codex. Quickstart opens a new thread with a prompt pointing at Runway Dev’s setup brief, and the agent installs the Runway Dev plugin from there.
Does the Open in Codex button work from the terminal?
No. The Quickstart buttons are app deep links, so they hand off to the Codex app. From the terminal, use Copy prompt in Quickstart and paste the prompt into Codex instead.
Can I use Runway Dev with ChatGPT?
Yes. ChatGPT installs the same Runway Dev plugin from the plugin directory it shares with Codex. That works for asking about your account, your models and your tasks. For building an integration, use Codex, since it is the surface that works inside your codebase.
Do I put my Runway API key in the Codex plugin or MCP config?
No. The connection uses OAuth in the browser, so no key belongs in the plugin, config.toml or any other MCP config. Keys stay in your Runway Dev account, where you can rotate them.
Do I still need a Runway API key with Codex?
Yes, for live generation calls from your app. Codex asks for RUNWAYML_API_SECRET in the project environment the first time it is ready to run something. Add it yourself rather than pasting it into the thread.
How do I know Codex is connected to Runway Dev?
Ask who you are and how many credits you have. It returns the email on your Runway Dev account and your current credit balance.
Are there Runway Dev skills for Codex?
Yes, seven, and the Runway Dev plugin installs all of them. To install them without the plugin, run npx skills add runwayml/skills --skill runway-dev-setup --skill runway-dev --skill <surface-skill> -a codex -y. The surface skills cover models, Model Routers, Characters, Recipes and Workflows.
Can Codex create a Model Router for me?
Yes. Ask for a router with the settings you want and for the integration to be updated to use it. It creates the configuration, reads it back, and rewrites the calling code to pass the config ID.
Can Codex spend my credits without asking?
No. Runway Dev’s setup brief tells the agent to treat a billable test call as optional unless you asked for one, and to ask before creating or changing anything live in the account.
How does Codex debug a failed generation?
It looks the task up through the MCP and reads the recorded cause, such as a moderation rejection, an asset over a size limit or a malformed request body, instead of guessing from the error string.
What can I build with Codex and Runway Dev?
Video, image and audio generation, real-time conversational video agents through Characters, upscaling and HDR output, using models from Runway and from other frontier labs.


