# Core concepts

> The objects Ryph uses to turn an instruction into an isolated run and a reviewable change.

Ryph runs coding agents on infrastructure you control. An orchestrator accepts work, launches an agent environment, and tracks its progress. Gateways mediate access to model providers, tools and connected Git repositories.

These pages explain how the system works today. They focus on the platform’s boundaries and data flow. To install Ryph, start with [Try it locally](https://ryph.ai/docs/try-locally.md).

## Agents, tasks and runs

An **agent** is an editable blueprint: its identity, harness, model policy, tools and instructions. It is not a permanently running process.

A **task** is an accepted piece of work. It records the requested instructions and checkout. A **run** is an execution attempt at that task, with a snapshot of the agent and the permissions resolved for that attempt.

Changing a blueprint affects future runs. It does not silently give a running agent a different model policy, a new tool grant or more internet access. Credential revocation and provider-key liveness can still take access away.

| Object   | What it owns                                       |
| -------- | -------------------------------------------------- |
| Agent    | The reusable blueprint                             |
| Task     | The accepted request and checkout                  |
| Run      | An execution attempt, frozen scopes and result     |
| Patch    | A delivered bundle’s metadata and submission state |
| Response | An incident conversation associated with a run     |

## Checkouts and workspaces

A task can target one repository or a workspace containing several. The runner creates a separate clone for each member under the checkout root, so the harness can work across repositories in one environment.

Every repository goes through the forge gateway, including one on your own machine: cloning is read-only, and changes leave as bundles. Each changed repository has its own patch and submission policy. A run working on an existing pull request can update that pull request’s branch instead of opening another.

## Scopes are permissions for one run

The orchestrator resolves several kinds of scope before launching work:

- **Model scope** selects the provider key and allowed models.
- **Tool scope** selects MCP servers and their allowed tools.
- **Forge policy** controls the platform’s issue and pull request actions.
- **Memory policy** controls participation in shared memory.
- **Network scope** selects allowed internet hosts within the deployment’s ceiling.

These policies have different defaults. In proxy mode, an agent without a network override inherits the deployment’s host allowlist. A missing ordinary MCP tool policy does not grant arbitrary servers. Platform memory, chat and forge tools have their own composition rules.

## Several ways to start work

The web app and HTTP API can create tasks. Automations use schedules or authenticated webhooks. Comments on GitHub issues and pull requests, GitLab issues and merge requests, or Radicle issues and patches, can invoke an agent with `/ryph <handle> <instructions>` after the commenter’s write access is checked.

An incident automation can keep a response open. Later alerts about the same alert group or incident join that run’s inbox; alerts without a key share one response per automation. Incident chat can run in a linked Telegram group, Zulip topic, Slack channel or Discord thread. In chat command rooms, mentioning the agent starts a run and further mentions steer it.

> [!WARNING]
> **Context does not grant authority**
>
> A webhook payload, repository file or chat message can provide information to an agent. It cannot edit the run’s granted scopes. Framing text as untrusted helps the model interpret it, but does not make prompt injection impossible.

## Follow the implementation

The central object definitions live in [orchestrator types](https://github.com/ryph-hq/ryph/blob/main/packages/orchestrator/src/core/types.ts). [Task creation](https://github.com/ryph-hq/ryph/blob/main/packages/orchestrator/src/core/start_task.ts) resolves the checkout, snapshots the agent and constructs the launch environment.