DocsGetting startedHosted quick start

Hosted quick start

Create a workspace in the hosted application, then create a workspace-scoped key for the coding tool you will connect.

Hosted4 part task

Prerequisites: A browser, an OROTOV account, and permission to create a workspace and its keys.
Action: Open the application and select Create free workspace.
hosted application
https://app.orotov.com
Expected result: The workspace appears in the application. Create a workspace key in its settings; the raw key is shown once, so save it in the connected tool configuration.
If it fails: If workspace creation fails, sign in and check that your account can create a workspace. Keep keys out of screenshots and public logs.

Public siteorotov.com

Applicationapp.orotov.com

API and MCPapi.orotov.com

Workspace records use workspace-scoped access. Provider settings and internal network details remain with the operator.

DocsGetting startedLocal CLI

Local CLI

Use the local CLI to run an OROTOV stack on your machine. It is separate from the hosted application.

Release candidate4 part task

Prerequisites: Python and an available local port 8000. The published Python CLI is prerelease 0.1.0rc1.
Action: Python prerelease install
pip install --pre orotov-cli
local database migration
orotov migrate
start server
orotov start
Expected result: The local server listens at http://localhost:8000. The CLI manages this local stack. It does not connect to a hosted workspace.
If it fails: Check the Python environment, run the migration, and confirm that port 8000 is free. Keep secrets out of copied logs.

DocsGetting startedConnect a coding tool

Connect a coding tool

Use the published npm package to add the OROTOV MCP endpoint to a supported coding tool. MCP provides workspace tools; workflow skills provide task guidance.

Stable package4 part task

Prerequisites: Node 18 or newer and a workspace API key shown by the application. Package @orotov/connect is stable at 0.1.0.
Action: hosted MCP command
npx @orotov/connect <API_KEY> --url https://api.orotov.com/mcp
Expected result: The package writes an OROTOV MCP entry for https://api.orotov.com/mcp. The package also installs the workflow rules file.
If it fails: If npm cannot find the package, check the public registry, package name, and version. For a 401, verify the workspace key and selected workspace without sharing the key.

DocsConnectorsGitHub connector

GitHub connector

The GitHub integration is a pre-GA pilot. An operator configures the GitHub App and webhook secret. The connector is designed to observe signed push, pull request, review, and check events.

Pilot, pre-GA4 part task

Prerequisites: An operator-configured GitHub App installed on the repository, access for that installation, and a matching webhook secret.
Action: Ask the operator to install the App, register the repository in the workspace, and send a signed test delivery.
Expected result: Use a signed test delivery to check the operator configuration. The connector event path is pre-GA and not generally available.
If it fails: Check the webhook secret and App installation first. A workspace key authenticates a coding tool; it does not validate GitHub webhook deliveries.

Private repositories are supported when the GitHub App installation has access. No repository source or credentials are exposed by this guide.

DocsTrust boundariesAuthentication and scoped keys

Authentication and scoped keys

A workspace API key lets a coding tool act within one workspace. It is separate from the person's application session and the GitHub App credential.

Credential boundaries4 part task

Prerequisites: Permission to manage workspace keys and a record of which tool will use the key.
Action: Create a named key and copy it when the application shows it once. Store it in the connected tool's protected configuration. To rotate it, update the tool with a replacement key, then revoke the old one.
Expected result: The application session authenticates a person. The key authenticates a tool to one workspace. A revoked key no longer authenticates.
If it fails: For a 401 response, check whether the key is invalid, revoked, or tied to a different workspace. Do not copy it into public logs.

User sessionAuthenticates a person in the application.
Workspace API keyAuthenticates a tool to one scoped workspace.
GitHub App credentialOwned by the operator and used for the repository integration boundary.
Provider secretsRemain in operator-managed deployment configuration and are never user setup values.

DocsTrust boundariesEvidence trust boundary

Evidence trust boundary

People and agents can write L0 Claimed evidence. Calling an MCP tool or workflow skill records an actor claim; it does not independently verify that claim.

Reality outranks testimony4 part task

Prerequisites: A work item with clear acceptance criteria. Use a connector or independent check when the work needs evidence above L0 Claimed.
Action: Use a skill or MCP tool to report work. A connector can observe an external artifact, and an independent system can verify an outcome.
Expected result: Connectors can record L1 Observed evidence for source artifacts. Independent systems can record L3 Verified evidence for supported outcomes such as a successful check.
If it fails: If no connector or independent system has confirmed the result, leave the record at Claimed. Check the source integration when an expected observation is missing.

L0 ClaimedL1 ObservedL3 Verified

DocsHelpTroubleshooting

Troubleshooting

Use the symptom below to check the relevant package, workspace key, GitHub setup, or local process.

Safe failure guidance4 part task

Prerequisites: The command you ran, its non-secret error message, and whether you are using hosted MCP or the local CLI.
Action: Find the matching error, correct the related setting, and retry.
Expected result: The package installs, the tool authenticates to the intended workspace, a signed GitHub event is accepted, or the local server starts.
If it fails: Remove credentials from any report. Include the package version, time, and non-secret error text when asking for help.

npm reports 404 or not found

Check that npm uses the public registry and that @orotov/[email protected] is the package and version you intended to install.

PyPI cannot find a stable release

The published Python CLI version is 0.1.0rc1. This prerelease requires --pre, so use pip install --pre orotov-cli.

MCP returns 401

The key may be invalid, revoked, or tied to another workspace. Select or create the correct workspace key. Do not publish it.

GitHub deliveries are rejected or absent

Check the webhook secret, operator setup, and repository access granted to the GitHub App.

The local service does not start

Run orotov migrate, then check whether another process is using port 8000.

Set up OROTOV and connect a coding tool with workspace-scoped access.