Skip to content
Back to search

orloj

SkillWorks with Claude CodeGitHub

Author and operate Orloj agents from Codex.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ammarisme--orloj-mcp/badge.svg)](/listings/ammarisme--orloj-mcp)

HTML

<a href="/listings/ammarisme--orloj-mcp"><img src="/api/listings/ammarisme--orloj-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

After the marketplace is pushed to GitHub, install [uv](https://docs.astral.sh/uv/) and run:

codex plugin marketplace add ammarisme/orloj-mcp --ref dev
codex plugin add orloj@orloj-marketplace

Restart Codex and start a new chat. Ask: “Use Orloj to list my agents.” The plugin runs its MCP server locally; it connects to `http://127.0.0.1:18080` by default. Your Orloj instance must already be running. The first launch may download Python dependencies. The GitHub marketplace is separate from OpenAI's public plugin directory.

To connect the installed plugin to another instance, create `~/.config/orloj-mcp/config.toml` with your own settings:

url = "https://your-orloj.example.com"
# token = "your-bearer-token"
# timeout = 30

The token is optional if your instance does not require one. Protect this file with `chmod 600 ~/.config/orloj-mcp/config.toml` and do not share or commit it. `ORLOJ_URL`, `ORLOJ_TOKEN`, and `ORLOJ_TIMEOUT` override the corresponding file settings when present in the server process environment. Restart the plugin/client after changes. Remote connections with credentials should use HTTPS.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

plugin.json · Manifest · 21 lines
  1. {
  2. "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  3. "name": "orloj",
  4. "version": "0.1.0",
  5. "description": "Author and operate Orloj agents from Codex.",
  6. "repository": "https://github.com/ammarisme/orloj-mcp",
  7. "keywords": ["orloj", "agents", "orchestration"],
  8. "extensions": {
  9. "com.openai": {
  10. "interface": {
  11. "displayName": "Orloj",
  12. "shortDescription": "Author and manage Orloj agents",
  13. "longDescription": "Connect to an Orloj instance to inspect, author, review and operate agents.",
  14. "developerName": "Ammar",
  15. "category": "Developer Tools",
  16. "capabilities": ["Read", "Write"],
  17. "defaultPrompt": ["List my Orloj agents", "Review my Orloj agent configuration"]
  18. }
  19. }
  20. }
  21. }
README.md · README · 78 lines
  1. # Orloj MCP
  2. An MCP server for managing an [Orloj](https://orloj.dev/) instance from Codex or another MCP client. It uses stdio: your client starts the process; no additional HTTP server is needed.
  3. ## Install the Codex plugin
  4. After the marketplace is pushed to GitHub, install [uv](https://docs.astral.sh/uv/) and run:
  5. ```sh
  6. codex plugin marketplace add ammarisme/orloj-mcp --ref dev
  7. codex plugin add orloj@orloj-marketplace
  8. ```
  9. Restart Codex and start a new chat. Ask: “Use Orloj to list my agents.” The plugin runs its MCP server locally; it connects to `http://127.0.0.1:18080` by default. Your Orloj instance must already be running. The first launch may download Python dependencies. The GitHub marketplace is separate from OpenAI's public plugin directory.
  10. To connect the installed plugin to another instance, create `~/.config/orloj-mcp/config.toml` with your own settings:
  11. ```toml
  12. url = "https://your-orloj.example.com"
  13. # token = "your-bearer-token"
  14. # timeout = 30
  15. ```
  16. The token is optional if your instance does not require one. Protect this file with `chmod 600 ~/.config/orloj-mcp/config.toml` and do not share or commit it. `ORLOJ_URL`, `ORLOJ_TOKEN`, and `ORLOJ_TIMEOUT` override the corresponding file settings when present in the server process environment. Restart the plugin/client after changes. Remote connections with credentials should use HTTPS.
  17. ## Run as a standalone MCP server
  18. Install Python 3.12+ and [uv](https://docs.astral.sh/uv/), and start Orloj. From a checkout:
  19. ```sh
  20. uv run python server.py
  21. ```
  22. Or run the package directly from GitHub, after these changes have been pushed to the `dev` branch:
  23. ```sh
  24. uvx --from 'git+https://github.com/ammarisme/orloj-mcp.git@dev' orloj-mcp
  25. ```
  26. The default address is `http://127.0.0.1:18080`. Set `ORLOJ_URL` for another instance and `ORLOJ_TOKEN` for bearer authentication. `ORLOJ_TIMEOUT` is the HTTP timeout in seconds (default 30). Set environment variables in your MCP client rather than committing tokens. Remote HTTP credentials should be sent only over HTTPS.
  27. Example Codex configuration in `~/.codex/config.toml`, after pushing this branch:
  28. ```toml
  29. [mcp_servers.orloj]
  30. command = "uvx"
  31. args = ["--from", "git+https://github.com/ammarisme/orloj-mcp.git@dev", "orloj-mcp"]
  32. [mcp_servers.orloj.env]
  33. ORLOJ_URL = "http://127.0.0.1:18080"
  34. # ORLOJ_TOKEN = "your-token" # Prefer a secure environment or secrets mechanism.
  35. ```
  36. Restart the client after changing configuration. For local development, set the command to `uv` and arguments to `--directory`, the absolute checkout path, `run`, `python`, `server.py`.
  37. ## What it exposes
  38. - Tools: list, inspect, create, replace, and delete agents; submit and inspect tasks; and call other Orloj HTTP API endpoints through `orloj_api`.
  39. - Resource template: `orloj://agents/{namespace}/{name}` reads an agent.
  40. - Prompt: `review_agent` instructs a client to fetch and review an agent. Client support for resources and prompts varies.
  41. Creating a task requires a complete Task manifest referring to an AgentSystem; an Agent is not directly runnable as a Task. Agent updates are full replacements, not patches; fetch the manifest first, retain the fields you want, and use `if_match` when appropriate. Orloj may rename a resource if the replacement manifest changes `metadata.name`.
  42. The generic tool takes a relative absolute path (such as `/v1/agent-systems`), HTTP method, optional query parameters, JSON or text body, and optional non-authentication headers. It supports JSON, text, and base64-encoded binary responses. Streaming responses, including server-sent events, are not supported. Tool calls have the permissions of the configured Orloj identity, including delete and administrative actions. Configure client approvals and Orloj authorization appropriately. Do not paste secrets into prompts or commit them to manifests.
  43. ## Let Orloj call Codex
  44. See `examples/codex-tool.yaml`. On the Orloj **worker host**, install and authenticate Codex, replace the placeholder command and working directory with absolute paths, and ensure the workspace is trusted. Configure an explicit worker host-command allowlist using `ORLOJ_CLI_TOOL_ALLOWED_COMMANDS` or `--cli-tool-allowed-commands`, including the exact Codex executable path. The operator must allow host CLI tool creation and execution. Apply the manifest with `orlojctl apply -f examples/codex-tool.yaml`, then attach `codex-workspace` to an agent's `spec.tools` and configure its permissions.
  45. The tool runs `codex exec` with `workspace-write`, so tasks can edit the selected workspace. Codex and its credentials must be accessible to the worker process; if Orloj runs inside Docker, a path on your Mac is not automatically available inside the container. This host mode does not provide Orloj container isolation. Grant access only to trusted agents. The worker's PATH, HOME, Codex login, outbound connectivity, task timeout, and approval configuration affect execution. The prompt sent by Orloj is a new Codex task, not this chat's conversation history; include any needed context explicitly.
  46. ## Development
  47. ```sh
  48. uv sync
  49. uv run python -m unittest discover -s tests -v
  50. uv run mcp dev server.py
  51. ```

Version history

  • v0.1.011/21/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.