Codex (Enterprise)

Use this guide to install the private Gomboc Enterprise skills plugin for Codex.

This plugin is distributed only as a private zip package shared via Google Drive during Gomboc Enterprise onboarding. It is not published on any public marketplace.

What you will set up

By the end of this guide, you will have:

  • The Gomboc Enterprise plugin package extracted locally on your machine

  • The Gomboc Enterprise marketplace added to OpenAI Codex

  • The gomboc plugin installed and enabled in Codex

  • A valid GOMBOC_API_TOKEN configured

  • Docker available so the ORL container runtime can run

  • A working Codex flow for Gomboc enterprise remediation and rule workflows

For background on ORL, see ORL (Open Remediation Language). For Gomboc rule concepts, see Rules

Who this is for

This guide is for Gomboc Enterprise customers who:

  • use OpenAI Codex as their coding agent

  • have a valid Gomboc Enterprise subscription

  • need enterprise remediation, rule authoring, or rule publishing workflows


Prerequisites

Before you start, make sure you have the following:

OpenAI Codex

  • OpenAI Codex must be installed and authenticated on your machine.

  • Open Codex and confirm that the plugin browser is available: /plugins

Enterprise Skills Plugin Package

  • The plugin is distributed as a zip package via a Google Drive link shared by your Gomboc contact during onboarding.

  • Download the zip and extract it to a stable location on your machine (for example ~/gomboc/gomboc-enterprise-skills/). The same extracted folder works for all four supported agent runtimes; you only need to do this once.

  • To upgrade later, download the new zip your Gomboc contact provides and replace the extracted folder (or extract alongside and re-point the install commands to the new path).

The zip contains the full plugin — every per-agent manifest (plugin.json, gemini-extension.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json) plus all skills, commands, and reference files.

Gomboc API token

Docker (for the ORL runtime)

  • The Gomboc Enterprise plugin runs ORL through the public gombocai/orl:latest container image, managed automatically by the agent.

  • Install Docker Desktop or Docker Engine for your operating system and confirm the daemon is running: docker info

For advanced ORL usage, see Custom Rules Quickstart


Step 1: Download and extract the plugin package

Download the zip file from the Google Drive link your Gomboc contact provided and extract it:

For the rest of this guide, the path ~/gomboc/gomboc-enterprise-skills/ refers to the extracted folder. Adjust it to wherever you extracted the zip.

Codex reads the marketplace manifest at the root of the extracted folder.

Step 2: Add the Gomboc marketplace and install the plugin

Add the marketplace from the absolute path to the extracted folder, then install the plugin from the plugin browser.

Then in Codex:

  1. Open Codex: codex and open the plugin browser: /plugins

  2. Select the Gomboc Enterprise marketplace.

  3. Open the gomboc plugin.

  4. Install the plugin.

  5. Make sure the plugin is enabled.

  6. Restart Codex if prompted.

Alternative: install from the command line

If you prefer a non-interactive install (for example for scripted setups or CI), skip the plugin browser and install the plugin directly from the terminal:

The -c GOMBOC_API_TOKEN=... flag injects the token into the plugin configuration as part of the install. If you use this form, you can skip Step 3 below; otherwise, leave the -c flag out and configure the token via ~/.codex/config.toml as described in Step 3. Restart Codex once the install completes.

Step 3: Configure your Gomboc token

Configure the plugin with your Gomboc API token.

Add the token to your Codex configuration file:

The Codex configuration file is usually located at: ~/.codex/config.toml

Keep this token private. Do not commit it to source control.

After updating the configuration, restart Codex so the plugin can read the new token.

Step 4: Confirm the ORL runtime

The gomboc plugin's orl skill resolves the runtime for you. It uses a local orl binary when one is on your PATH, and otherwise runs ORL through the gombocai/orl:latest Docker container (pulled automatically on first use). You do not invoke the runtime directly.

Verify the integration end-to-end by asking the agent to run the orl skill with the version subcommand. The skill prints the resolved ORL version and reports the execution method (local binary or container image).

In Codex, invoke the orl skill: $orl version

If the call fails (no version returned, or an error referencing the runtime), see ORL runtime not available under Troubleshooting below.

Step 5: Run your first Gomboc workflow

Once the plugin, token, and ORL runtime are configured, use the Gomboc skills installed in Codex.

Codex uses native skill invocation rather than Claude or Gemini slash commands. You can invoke installed skills with $skill-name, use /skills, or select the relevant installed skill from the Codex interface.

Diagnose a codebase

Use: $diagnose

  • This workflow helps analyze source code against Gomboc-supported security and policy classifications.

Fix a concrete issue in code

Use the Codex-native fix flow:

  • This workflow helps analyze the violation context, build a targeted ORL rule, and apply the remediation after review.

Enforce a policy end to end

Use: $enforce-policy

  • This workflow helps diagnose a policy, assess rule coverage, apply existing rules, create missing rules when needed, and verify compliance.

Create a reusable rule

Use: $build-rule

  • This workflow helps create a reusable ORL rule from a policy, classification, or requirement.

Release or publish a rule

Use: $release-rule

  • This workflow supports enterprise rule release and publishing flows.

  • For details about publishing ORL rules, see Publish and Rule Service API


Troubleshooting

Use this section to diagnose the most common setup issues.

Plugin package download or extraction issues

If the zip file provided by your Gomboc contact cannot be downloaded or extracted:

  • Confirm the Google Drive link is still valid and has not expired. Ask your Gomboc contact to re-share if needed.

  • Confirm the download completed fully before extracting — a partial download will fail silently or produce an empty folder.

  • On macOS, if unzipping via Finder produces an incomplete result, prefer the terminal: unzip ~/Downloads/gomboc-enterprise-skills.zip -d ~/gomboc/

  • Confirm you have write access to the destination folder.

If you are still unable to obtain the package, contact your Gomboc representative.

Marketplace add fails

If codex plugin marketplace add ~/gomboc/gomboc-enterprise-skills fails:

  • Confirm the path you passed is the absolute path to the extracted folder, not a relative path or a ~-only fragment.

  • Confirm the folder exists and contains the marketplace manifest at its root.

  • Confirm you have read permission on the folder: ls -la ~/gomboc/gomboc-enterprise-skills

  • Retry the command after fixing the path.

Marketplace does not appear in Codex

If the marketplace was added but does not appear in the plugin browser:

  • Restart Codex.

  • Reopen /plugins.

  • Check that the marketplace source is the absolute path to the extracted folder.

  • Upgrade configured marketplaces: codex plugin marketplace upgrade

If the problem persists, remove and re-add the marketplace:

  • codex plugin marketplace remove gomboc-enterprise-marketplace

  • codex plugin marketplace add ~/gomboc/gomboc-enterprise-skills

Plugin does not appear after adding the marketplace

If the marketplace appears but the gomboc plugin is missing:

  • Confirm the extracted plugin folder is still present at the path you used when adding the marketplace.

  • Restart Codex.

  • Reopen /plugins.

  • Upgrade the marketplace: codex plugin marketplace upgrade gomboc-enterprise-marketplace

Token configuration errors

If the plugin reports authentication or token errors:

  • Confirm that GOMBOC_API_TOKEN is configured in ~/.codex/config.toml.

  • Confirm that the token is valid and has not expired.

  • Generate or rotate your token — see Generate A Personal Access Token

  • Restart Codex after updating the token.

ORL runtime not available

If Codex or a Gomboc skill reports that ORL cannot be executed:

  • Run docker info to confirm Docker is installed and the daemon is running.

  • Pull the image manually to confirm registry access: docker pull gombocai/orl:latest

  • If you maintain a local orl binary, confirm it is on PATH with command -v orl.

  • Restart your terminal and Codex after fixing Docker or PATH.

ORL command runs but remediation fails

If ORL is available but remediation does not complete:

  • Confirm that you are running Codex from the correct project or workspace.

  • Confirm that the target files are supported by the workflow you are running.

  • Confirm that your GOMBOC_API_TOKEN is valid.

  • Review the Codex and ORL output for rule, language, workspace, or authentication errors.

For ORL concepts and supported rule workflows, see ORL (Open Remediation Language) and Workspace

Skills do not appear in Codex

If the plugin is installed but Gomboc skills do not appear:

  • Confirm that the gomboc plugin is installed and enabled in /plugins.

  • Restart Codex.

  • Open /skills and search for Gomboc skills such as diagnose, enforce-policy, analyze-context, build-fix, or apply-fix.

  • Upgrade the marketplace and reinstall the plugin if needed.

Plugin updates do not appear

If a new version of the plugin is available but Codex still shows an older version:

  • Download the latest zip from the Google Drive link your Gomboc contact provided and replace the extracted folder.

  • Refresh Codex's view of the marketplace: codex plugin marketplace upgrade gomboc-enterprise-marketplace

  • Restart Codex.

Still need help?

If you are still blocked, contact the Gomboc team with:

  • the step where the setup failed

  • the error message you received

  • the absolute path to your extracted plugin folder

  • the output of codex --version

  • the output of docker info (or orl --help, if you use a local binary)

See Support for support channels.

Last updated