Getting Started

Run headless OpenAI Codex CLI sessions as one-shot jobs in Eyevinn Open Source Cloud. You provide a git repository and a prompt; Codex Runner clones the repo and executes the task non-interactively inside a container using codex exec.

This is useful for automated code review, report generation, CI-triggered agent runs, batch processing, and scheduled agentic tasks where you want Codex's full file system and tool access without running it locally.

Prerequisites

• If you have not already done so, sign up for an OSC account.
• NodeJS installed on your local computer.
• A git repository with an AGENTS.md file describing the project and task context (see Preparing Your Repository below).
• An OpenAI API key (see Authentication below).

Authentication

Codex Runner requires an OpenAI API key to authenticate with the Codex CLI.

OpenAI API Key

Obtain an API key from platform.openai.com. The key starts with sk-. This is the only authentication method supported by Codex Runner.

Store Credentials as OSC Secrets

Keep sensitive values out of your commands by storing them as OSC service secrets. Read the guide on how to work with secrets for instructions on how to create a secret and refer to it.

Recommended secrets to create before running jobs:

Secret name	Value
openaikey	Your OpenAI API key (sk-...)
gittoken	A GitHub PAT or Gitea token, for private repositories
oscaccesstoken	Your OSC personal access token, if the job manages OSC services via MCP

Once created, reference a secret in any option value using the {{secrets.secretname}} syntax.

Inject Environment Variables with a Parameter Store

For jobs that need additional configuration such as API keys for Slack, webhook URLs, database credentials, or any other environment variables, use an OSC Application Config Service (parameter store) together with the ConfigSvc option.

When ConfigSvc is set (along with OscAccessToken), Codex Runner loads all key-value pairs from the parameter store and injects them as environment variables before the Codex session starts. This means your AGENTS.md or any scripts can reference these variables, and any tools Codex runs will have access to them.

Setting up a parameter store

1. Create a parameter store using the OSC CLI or web console:

npx -y @osaas/cli create eyevinn-app-config-svc myagentconfig \
  -o RedisUrl="<valkey-url>"

Or use the setup-parameter-store helper which creates both the Valkey instance and the config service in one step.

1. Set the environment variables your job needs:

curl -X PUT "https://<tenant>-myagentconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config/SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"value": "https://hooks.slack.com/services/T00/B00/xxxx"}'

1. Reference the parameter store name in ConfigSvc when creating a Codex Runner job (see the example below).

Examples

Here are some examples of use cases that Codex Runner can handle and how to create jobs with the Open Source Cloud CLI. Before running any of the examples, set your personal access token in the environment variable OSC_ACCESS_TOKEN.

% export OSC_ACCESS_TOKEN=<your-personal-access-token>

You find your personal access token in the Open Source Cloud web console (Settings/API).

Code Review

Analyze a public repository for potential bugs and security issues.

% npx -y @osaas/cli create birme-codex-runner codereview \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o SourceUrl="https://github.com/myorg/myrepo" \
  -o Prompt="Review the code in src/ for potential bugs and security issues. Write a summary report to review.md."

Run a Scheduled Task from an Agent Repository

Run a daily report task defined in a dedicated agent repo containing an AGENTS.md with instructions.

% npx -y @osaas/cli create birme-codex-runner dailyreport \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o SourceUrl="https://github.com/myorg/agent-tasks#main" \
  -o Prompt="Run the daily report task" \
  -o Model="o3-mini"

The #main suffix pins the job to the main branch. Use any valid branch name or omit the fragment to use the default branch.

Work on a Specific Subdirectory in a Monorepo

Use SubPath to scope Codex to a single package within a larger repository.

% npx -y @osaas/cli create birme-codex-runner analyze \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o SourceUrl="https://github.com/myorg/monorepo" \
  -o SubPath="packages/api" \
  -o Sandbox="danger-full-access" \
  -o Prompt="Analyze the API package and suggest performance improvements."

With OSC MCP Integration

Supply OscAccessToken to give Codex Runner access to the OSC MCP server at mcp.osaas.io/mcp. This lets Codex manage OSC services, check instance health, and perform operations through the platform's AI interface.

% npx -y @osaas/cli create birme-codex-runner oscops \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o OscAccessToken="{{secrets.oscaccesstoken}}" \
  -o SourceUrl="https://github.com/myorg/infra-config" \
  -o Sandbox="danger-full-access" \
  -o Prompt="Check the health of all my OSC service instances and create a status report in status.md."

Inject Environment Variables from a Parameter Store

Use ConfigSvc to load environment variables (such as API keys for Slack or other services) from an OSC parameter store into the job. This requires OscAccessToken to be set as well.

% npx -y @osaas/cli create birme-codex-runner slackreport \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o OscAccessToken="{{secrets.oscaccesstoken}}" \
  -o ConfigSvc="myagentconfig" \
  -o SourceUrl="https://github.com/myorg/agent-tasks" \
  -o Sandbox="danger-full-access" \
  -o Prompt="Generate the weekly status report and post it to Slack using the SLACK_WEBHOOK_URL environment variable."

In this example, the parameter store myagentconfig contains a key SLACK_WEBHOOK_URL. Codex Runner loads it as an environment variable before starting, so Codex can use it in commands or scripts.

Private Repository with Git Token

Pass a GitHub PAT or Gitea token via GitToken to clone private repositories.

% npx -y @osaas/cli create birme-codex-runner privreview \
  -o CodexApiKey="{{secrets.openaikey}}" \
  -o GitToken="{{secrets.gittoken}}" \
  -o SourceUrl="https://github.com/myorg/private-repo" \
  -o Sandbox="danger-full-access" \
  -o Prompt="Run the test suite and report any failures with suggested fixes."

Preparing Your Repository

Codex Runner clones whatever repository you point it to, then executes Codex from the root (or SubPath if set). For best results, prepare the repository as follows.

Add an AGENTS.md file at the repository root. This is the Codex CLI's primary context document. Include:

• A description of what the project does
• Coding conventions and style guidelines
• Instructions for how Codex should approach tasks in this repo
• Any environment details or constraints

Optionally add a .codex/ directory for Codex-specific configuration.

The repository should contain whatever source code, configuration files, or data Codex needs to accomplish the task you specify in Prompt.

Sandbox Mode

The Sandbox option controls the level of system access granted to Codex during the job.

By default, Codex runs in a restricted read-only mode. To allow Codex to write files, run shell commands, and perform other modifications, set Sandbox to danger-full-access.

Value	Behavior
(unset)	Read-only mode; Codex can inspect but not modify the file system
danger-full-access	Full system access; Codex can read, write, and execute commands

For tasks that produce output (writing reports, modifying code, running tests), set Sandbox="danger-full-access".

Configuration Options

Option	Required	Secret	Description
name	Yes	No	Job name (alphanumeric only)
Prompt	Yes	No	The task or instruction for Codex to execute
SourceUrl	Yes	No	Git repository URL; append #branch for a specific branch
CodexApiKey	Yes	Yes	OpenAI API key (sk-...)
GitToken	No	Yes	GitHub PAT or Gitea token for private repositories
Model	No	No	Model to use, e.g. o3-mini, gpt-4.1
Sandbox	No	No	Sandbox mode: danger-full-access for full system access (default: read-only)
SubPath	No	No	Working subdirectory within the repo, for monorepos
OscAccessToken	No	Yes	OSC personal access token; auto-configures the OSC MCP server
ConfigSvc	No	No	Name of an OSC parameter store instance; loads its keys as env vars

Troubleshooting

Job exits immediately with an auth error: Verify that CodexApiKey is set and that the secret reference ({{secrets.openaikey}}) matches an existing secret in your OSC account.

Repository not found or clone fails: For private repositories, ensure GitToken is set with a token that has read access to the repo. Double-check the SourceUrl for typos.

Codex cannot write files or run commands: Ensure Sandbox="danger-full-access" is set. Without it, Codex runs in read-only mode and any write operations will fail.

SubPath not found: The path is relative to the repository root. Check the exact directory name in the repository and ensure it exists on the branch you are targeting.

Support

Join our Slack workspace for real-time support and to connect with other users.