Service: Claude Runner - EyevinnOSC/community GitHub Wiki
Claude Runner (source, serviceId birme-claude-runner) runs headless Claude Code sessions as one-shot jobs in Eyevinn Open Source Cloud (OSC). You provide a git repository and a prompt; the job clones the repo and runs the task non-interactively in a container. Service page: https://app.osaas.io/dashboard/service/birme-claude-runner. License: MIT.
- Automated code review and report generation against a git repository.
- CI-triggered and scheduled agent runs, batch processing and other agentic tasks with Claude Code's full file system and tool access.
- Read-only analysis or restricted runs by limiting tools with
AllowedToolsandDisallowedTools. - Manage OSC itself: when
OscAccessTokenis set, the OSC MCP server is configured for the session. - Load extra environment variables (API keys, webhook URLs) from an OSC parameter store.
Claude Runner has no dependencies on other OSC services. You need a git repository (ideally with a CLAUDE.md) and one credential: an Anthropic API key (sk-ant-...) or a Claude OAuth token. The OAuth token is the recommended method for access to all Claude Code features tied to a subscription; generate it by running claude setup-token locally and completing the browser flow.
- Store credentials with
create-service-secret(serviceIdbirme-claude-runner), for exampleclaudeoauthtoken(oranthropicapikey),gittokenfor private repos andoscaccesstokenif the job manages OSC. See Working with Secrets. - Create the job with
create-service-instance,serviceId: "birme-claude-runner":
{
"name": "codereview",
"ClaudeCodeOauthToken": "{{secrets.claudeoauthtoken}}",
"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.",
"MaxTurns": "10"
}- Follow progress with
get-instance-statusand read the output withget-logs-for-instance.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the job. Letters, digits and underscore only (^\w+$), at most 20 characters. |
| Prompt | Yes | string | The task for Claude to execute in the cloned repository, for example "Run the daily report task". |
| SourceUrl | Yes | string | Git repository URL to clone. Append #branch to pin a branch, for example https://github.com/myorg/agent-tasks#main. Alias GITHUB_URL. |
| AnthropicApiKey | One of this or ClaudeCodeOauthToken | string, sensitive | Anthropic API key, format sk-ant-.... |
| ClaudeCodeOauthToken | One of this or AnthropicApiKey | string, sensitive | Claude OAuth token from claude setup-token. |
| GitToken | No | string, sensitive | GitHub personal access token (for example ghp_...) or Gitea-style token, needed only for private repositories. Alias GITHUB_TOKEN. |
| Model | No | string | Claude model to use, for example claude-sonnet-4-5-20250514. Claude's default model is used when unset. |
| MaxTurns | No | string | Maximum number of agentic turns; limits runaway loops and execution time. |
| AllowedTools | No | string | Comma-separated whitelist of tools Claude may use, for example Read,Grep,Glob,WebFetch. |
| DisallowedTools | No | string | Comma-separated list of tools to block while keeping the rest, for example Edit,Write. |
| SubPath | No | string | Working subdirectory inside the repository, relative to its root. Useful for monorepos. |
| OscAccessToken | No | string, sensitive | OSC personal access token. Configures an HTTP MCP server for OSC at https://mcp.osaas.io/mcp in the session. Required for ConfigSvc. |
| ConfigSvc | No | string | Name of an OSC Application Config Service instance. With OscAccessToken set, its key-value pairs are loaded as environment variables before the session starts. |
| ConfigApiKey | No | string, sensitive | API key of the parameter store, used to decrypt secret parameters when set with OscAccessToken and ConfigSvc. |
| OscMcpUrl | No | string | Override URL for the OSC MCP server. Default https://mcp.osaas.io/mcp; set to an environment-specific URL for dev or stage. |
Store sensitive options as service secrets and pass them as {{secrets.NAME}} (whole field value only). Overwriting a secret does not restart a running instance.
For jobs that need extra configuration such as Slack webhooks or database credentials, create an Application Config Service instance (eyevinn-app-config-svc, backed by Valkey; see Service: App Config Svc and the Parameter Store guide), and set the variables:
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": "https://hooks.slack.com/services/T00/B00/xxxx"}'Then set ConfigSvc (and OscAccessToken) when creating the job. Your CLAUDE.md, skills and any Bash commands Claude runs can use the variables.
Here are some examples of use cases that Claude Runner can handle and how to create jobs with the Open Source Cloud CLI. The examples use the OSC CLI; set your personal access token in the environment variable OSC_ACCESS_TOKEN before running them. The same options can be passed in the config object of create-service-instance.
% export OSC_ACCESS_TOKEN=<your-personal-access-token>See Finding Your API Token for where to get your personal access token.
Analyze a public repository for potential bugs and security issues.
% npx -y @osaas/cli create birme-claude-runner codereview \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-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." \
-o MaxTurns="10"Run a daily report task defined in a dedicated agent repo containing a CLAUDE.md with instructions.
% npx -y @osaas/cli create birme-claude-runner dailyreport \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-o SourceUrl="https://github.com/myorg/agent-tasks#main" \
-o Prompt="Run the daily report task" \
-o Model="claude-sonnet-4-5-20250514" \
-o MaxTurns="25"The #main suffix pins the job to the main branch. Use any valid branch name or omit the fragment to use the default branch.
Use SubPath to scope Claude to a single package within a larger repository.
% npx -y @osaas/cli create birme-claude-runner analyze \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-o SourceUrl="https://github.com/myorg/monorepo" \
-o SubPath="packages/api" \
-o Prompt="Analyze the API package and suggest performance improvements." \
-o DisallowedTools="Edit,Write" \
-o MaxTurns="15"Setting DisallowedTools="Edit,Write" makes this a read-only analysis run; Claude can explore and report but cannot modify files.
Supply OscAccessToken to give Claude Runner access to the OSC MCP server at mcp.osaas.io/mcp. This lets Claude manage OSC services, check instance health, and perform operations through the platform's AI interface.
% npx -y @osaas/cli create birme-claude-runner oscops \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-o OscAccessToken="{{secrets.oscaccesstoken}}" \
-o SourceUrl="https://github.com/myorg/infra-config" \
-o Prompt="Check the health of all my OSC service instances and create a status report in status.md." \
-o MaxTurns="20"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-claude-runner slackreport \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-o OscAccessToken="{{secrets.oscaccesstoken}}" \
-o ConfigSvc="myagentconfig" \
-o SourceUrl="https://github.com/myorg/agent-tasks" \
-o Prompt="Generate the weekly status report and post it to Slack using the SLACK_WEBHOOK_URL environment variable." \
-o MaxTurns="15"In this example, the parameter store myagentconfig contains a key SLACK_WEBHOOK_URL. Claude Runner loads it as an environment variable before starting, so Claude can use it in Bash commands or scripts.
Pass a GitHub PAT or Gitea token via GitToken to clone private repositories.
% npx -y @osaas/cli create birme-claude-runner privreview \
-o ClaudeCodeOauthToken="{{secrets.claudeoauthtoken}}" \
-o GitToken="{{secrets.gittoken}}" \
-o SourceUrl="https://github.com/myorg/private-repo" \
-o Prompt="Run the test suite and report any failures with suggested fixes." \
-o MaxTurns="20"Claude Runner clones whatever repository you point it to, then executes Claude Code from the root (or SubPath if set). For best results, prepare the repository as follows.
Add a CLAUDE.md file at the repository root. This is Claude Code's primary context document. Include:
- A description of what the project does
- Coding conventions and style guidelines
- Instructions for how Claude should approach tasks in this repo
- Any environment details or constraints
Optionally add a .claude/ directory containing:
-
settings.jsonfor tool permissions and environment configuration -
skills/for reusable prompt templates Claude can invoke during the session
The repository should contain whatever source code, configuration files, or data Claude needs to accomplish the task you specify in Prompt.
AllowedTools and DisallowedTools let you restrict which Claude Code tools are available during a job. Both accept a comma-separated list of tool names.
Use DisallowedTools to block specific tools while keeping everything else available:
DisallowedTools="Edit,Write,Bash"
Use AllowedTools to create a whitelist; only the listed tools will be available:
AllowedTools="Read,Grep,Glob,WebFetch"
Common patterns:
| Goal | Setting |
|---|---|
| Read-only code analysis | DisallowedTools="Edit,Write" |
| Pure research, no file access | AllowedTools="WebFetch,WebSearch" |
| Read files only, no shell | AllowedTools="Read,Grep,Glob" |
| Full access (default) | Leave both options unset |
- The job stops when
MaxTurnsis reached; raise it or split the task.
Job exits immediately with an auth error: Verify that ClaudeCodeOauthToken or AnthropicApiKey is set and that the secret reference ({{secrets.name}}) 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.
Claude stops mid-task: The job may have reached MaxTurns. Increase MaxTurns or split the task into smaller jobs.
Claude modifies files you did not want changed: Use DisallowedTools="Edit,Write" to prevent file modifications, or use AllowedTools to define an explicit whitelist.
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.