Service: Codex Runner - EyevinnOSC/community GitHub Wiki

Codex Runner

Codex Runner (serviceId birme-codex-runner, catalog page) runs headless OpenAI Codex CLI sessions as one-shot jobs. You provide a git repository and a prompt; the job clones the repo and executes the task non-interactively in a container with codex exec. It is a job (runs and exits), not a long-running service. License: MIT.

What it can do

  • Automated code review, report generation, CI-triggered agent runs, batch processing and scheduled agentic tasks with Codex's file system and tool access, without running it locally.
  • Work on a branch (#branch suffix on SourceUrl) or a subdirectory of a monorepo (SubPath).
  • Clone private repositories with a Git token.
  • Optionally connect to the OSC MCP server (OscAccessToken) and load extra environment variables from an OSC App Config Service parameter store (ConfigSvc).

Creating an instance

You need an OpenAI API key (starts with sk-; the only supported authentication). Store sensitive values as service secrets with create-service-secret (serviceId: "birme-codex-runner"), for example openaikey, gittoken (GitHub PAT or Gitea token for private repos) and oscaccesstoken (OSC personal access token). Then call create-service-instance with serviceId: "birme-codex-runner":

{
  "name": "codereview",
  "CodexApiKey": "{{secrets.openaikey}}",
  "SourceUrl": "https://github.com/myorg/myrepo",
  "Prompt": "Review the code in src/ for potential bugs and security issues. Write a summary report to review.md."
}

Check progress with get-instance-status and get-logs-for-instance. The job runs and exits.

Options

Option Required Type Meaning
name Yes string Name of the job. Alphanumeric, at most 20 characters.
Prompt Yes string Task or prompt for Codex to execute on the cloned repository.
SourceUrl Yes string Git repository URL to clone. Append #branch to pin a branch; otherwise the default branch is used.
CodexApiKey No string, sensitive OpenAI API key for Codex. Either this or OpenaiApiKey must provide the key for the job to authenticate.
OpenaiApiKey No string, sensitive OpenAI API key; alias for CodexApiKey, normalized internally.
GitToken No string, sensitive Token (GitHub PAT or Gitea token) for cloning private repositories.
Model No string Model for the Codex session, e.g. o3-mini, gpt-4.1.
MaxTurns No string Maximum number of turns or iterations for the session.
AllowedTools No string Comma-separated list of tools Codex may use.
DisallowedTools No string Comma-separated list of tools Codex may not use.
SubPath No string Subdirectory within the repository used as the working directory (monorepos), relative to the repo root.
OscAccessToken No string, sensitive OSC personal access token; enables the OSC MCP server (mcp.osaas.io/mcp) and config service integration.
ConfigSvc No string Name of an OSC App Config Service instance whose key-value pairs are injected as environment variables before the session starts. Requires OscAccessToken.
ConfigApiKey No string, sensitive API key for accessing encrypted parameters in the parameter store.
Sandbox No string Used in the previous version of this page but not listed in the catalog option list I checked: danger-full-access gives full system access; unset means read-only. Confirm with get-service-schema before relying on it.

{{secrets.NAME}} must be the entire field value. Overwriting a secret does not restart a running job.

Using the instance

Sandbox. By default Codex runs read-only: it can inspect but not modify files. For tasks that write reports, change code or run commands, set Sandbox to danger-full-access (see the table row above).

Prepare the repository. Add an AGENTS.md at the repository root (project description, conventions, how Codex should approach tasks, environment constraints); optionally a .codex/ directory for Codex configuration. Codex runs from the repo root or from SubPath.

Parameter store. To pass extra variables (Slack webhooks, database credentials and so on), create an App Config Service instance (eyevinn-app-config-svc; it needs a Valkey instance), set the keys, then set ConfigSvc and OscAccessToken on the job. All key-value pairs become environment variables for the session.

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

curl -X PUT "https://<tenant>-myagentconfig.eyevinn-app-config-svc.auto.prod-se.osaas.io/api/v1/config/SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"value": "<webhook-url>"}'

Examples with the OSC CLI (set OSC_ACCESS_TOKEN to your personal access token first):

# Scheduled task from an agent repo, pinned to main, with a model
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"

# Monorepo subdirectory
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."

# OSC MCP integration
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."

# Environment variables from a parameter store
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."

# Private repository
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."

Limitations

  • Troubleshooting: an immediate auth error means CodexApiKey is missing or the {{secrets.NAME}} reference does not match an existing secret. A clone failure on a private repo means GitToken is missing or lacks read access, or SourceUrl is wrong. Codex cannot write or run commands without Sandbox set to danger-full-access. A SubPath not found error means the path does not exist on the targeted branch.
  • Only OpenAI API keys are supported for authentication.

Resources

⚠️ **GitHub.com Fallback** ⚠️