---
title: "Take over a running browser"
description: "Claim a live environment for a bounded window — to finish a login, unstick a flow, or look at what the Worker is looking at."
---

Sometimes the right move is to put your hands on the environment: a login the Worker cannot complete, a flow that has gone somewhere unexpected, or simply wanting to see what it sees. A **control lease** does that, for a bounded time.

<Warning>
A control lease is taken on a live run, and as of 2026-09-10 a run does not complete end to end ([Overview](/workers/overview)). The route answers; there is nothing to attend yet.
</Warning>

## Take the lease

```bash
curl -fsS -X POST "$WS/worker-runs/$RUN_ID/control-lease" \
  -H "Authorization: Bearer $OBOL_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment_class": "browser", "duration_seconds": 300, "purpose": "takeover"}'
```

```json 200
{
  "run_id": "wrun_eccb4b6f30cc472a936a0b1332e9dad1",
  "control_lease_id": "wcl_3d3f7b86f5a643f99cdd97fa322b2232",
  "holder_user_id": "usr_dana",
  "expires_at": "2026-09-09T23:07:23Z"
}
```

```ts
const lease = await obol.workers.takeControl(runId, {
  environment_class: "browser",
  duration_seconds: 300,
  purpose: "assisted_login",
});
```

`duration_seconds` is between 30 and 3600 and defaults to 300. `purpose` is `takeover`, `assisted_login` or `inspection`.

## Why it is time-boxed, and why it needs the higher grant

A control lease is how a user-assisted login happens, so it is the one place a person is at a keyboard inside an environment that may hold a session profile. An open-ended lease would be an unattended authenticated environment with extra steps — so the lease expires, by construction.

It is gated on `CHANGE_APPLY` rather than the propose grant. Check before you offer it:

```ts
const { capabilities } = await obol.workers.getRun(runId);
capabilities.can_take_control;  // false for a developer, true for admin and owner
```

A surface that renders a Take control button someone cannot use is the dashboard equivalent of listing a tool a key cannot call.

## What the lease is not

It is not a widening of what the Worker may do. It is the opposite: the lease is also the **only** place a high-impact arbitrary UI action may happen at all, and that restriction stands in every execution mode. `autonomous` asks for fewer approvals and enforces every limit; it does not turn an unattended agent into one that may click anything consequential. That is a semantic boundary — Obol cannot express the application-level meaning of an arbitrary click to a policy engine — rather than a preference somebody may flip.

The response carries the lease, its holder and its expiry. It never carries a handle to the environment itself; the run view's `control_lease` field reports who is attending and never the handle.

## After the takeover

Whatever you did by hand is *your* action, recorded as an attended interval. It does not become part of the Worker's typed record of what it did, and it does not raise what the run's evidence is worth: an observation made while a person was driving is still an observation of a screen.

If the run was paused while you worked, resume it — and note that resuming re-allocates, so concurrency is checked again and can refuse:

```ts
await obol.workers.resumeRun(runId);
```

A resume also re-reads current policy before the next attempt runs. A permission revoked while the run waited is not still granted.