# Workers

A Worker is a scoped, audited identity you hand an AI agent instead of your own keys. It can read your infrastructure and propose changes you approve - and it can never delete resources or read your secrets. You give a Worker an objective and orkestr runs the agent for you - on demand, on a schedule, or in reaction to an event - driven by your own model. Every action is recorded.

> **The idea**
>
> Handing an agent your API key means handing it the power to delete everything and read every secret. A Worker is the safe version of that handoff: a named identity with a role, an approval gate, and a complete audit trail.

## What a Worker can and cannot do

Every tool an agent might call falls into one of four tiers:

- **Read** - projects, logs, metrics, deployment history, and the project's source code (read-only). Allowed freely. The git credential stays server-side - a Worker reads the code, never your token.
- **Reversible** - working in an isolated environment. Allowed for roles that permit it.
- **Gated** - irreversible actions like a deploy, a rollback, or opening a pull request. These are never run directly; they are queued for your approval. A worker proposes the change (for a PR, it reads the code and submits the edits); orkestr only commits and opens the PR after you approve, using your git credential in the control plane - never in the runtime.
- **Never** - destructive or secret-revealing actions (deleting a project, reading environment variables, rotating keys). Permanently unreachable for a Worker, regardless of role or configuration.

## Roles

A Worker carries exactly one role. Two presets ship today:

- **Observer** - reads non-secret state, and nothing else. Best for investigation and monitoring.
- **Maintainer** - reads, works in isolated environments, and can *propose* a deploy or rollback. Proposals are queued for your approval; it still cannot delete anything or read a secret.

## Create a Worker

In the console, open **Workers** and choose **New worker**. Give it a name, pick a role, and optionally add standing instructions. A Worker runs on orkestr's hosted runtime. When it calls a gated tool it gets back a `pending` result and waits for your approval, rather than acting.

## Run a Worker

Give a Worker an objective and orkestr runs the agent loop for you in an isolated environment, driven by your own model.

- Add a model key once under **Workers** (bring your own - it is stored encrypted and used only to drive your runs).
- Press **Run** on a Worker, describe the objective, and it works on its own: inspecting your infrastructure, reasoning, and proposing changes.
- If it proposes a gated action, the run pauses at `pending approval` until you decide.

## Approvals

Gated actions queue in the console under **Pending approvals**, showing the tool and its arguments. Approve and the action runs; deny and it never does. The approval card shows the structured request, not free-form agent text, so the decision is always yours to make on the facts.

## Run history

Every unattended run is recorded with its full transcript - the model's reasoning, every tool call, every result, and the outcome. The **Run history** table on the Workers page is your complete, reviewable record of what your agents did. Audit is not an add-on; it is the point.

## The security model

Workers assume the agent can be manipulated by the data it reads (logs, tickets, repositories). The boundary does not depend on the agent behaving:

- Destructive and secret-revealing tools are unreachable, enforced before any policy lookup.
- Irreversible actions always require a human decision.
- Unattended runs execute in isolated, EU-hosted environments with a per-run, short-lived token.
- Personal API tokens and browser sessions are unaffected - only Worker tokens are gated.

> **Next**
>
> See the [Workers overview](https://orkestr.eu/ai-workers) for the product tour, or the [MCP server docs](https://orkestr.eu/docs/mcp) for the full tool surface.