Skip to main content
When you set scale > 1 on an agent, multiple instances run concurrently. Without coordination, two instances might pick up the same GitHub issue, review the same PR, or deploy the same service at the same time. Resource locks prevent this.

​
Why Locks Exist

Locks let concurrent agent instances claim exclusive ownership of a resource before working on it. If another instance already holds the lock, the agent skips that resource and moves on.

​
How It Works

  1. Before working on a shared resource, the agent calls acquire_lock with a resource URI (e.g. "github://acme/app/issues/42").
  2. If the lock is free, the agent gets it and proceeds.
  3. If another instance already holds the lock, the tool returns the holder’s identity — the agent skips that resource.
  4. When done, the agent calls release_lock.
The agent learns the locking guidelines from a skill block injected into its prompt. Agent authors just reference the tools in their SKILL.md workflow.

​
Tools

See Agent Tools — Scheduler Tools for the full tool reference.

​
Resource Key URIs

Lock keys use URI format. Use a scheme that identifies the resource type, and a path that uniquely identifies the instance:

​
TTL and Expiry

Locks expire automatically after 30 minutes by default. This prevents deadlocks if an agent crashes or hangs without releasing its lock. The timeout is configurable via resourceLockTimeout in config.toml (value in seconds). For work that takes longer than the timeout, acquire the lock with a larger ttl_seconds value. If the lock expires, another instance can claim it.

​
Multiple Locks and Deadlock Detection

An agent instance can hold multiple locks simultaneously when working across related resources. However, this introduces the possibility of circular waits — agent A holds lock X and waits for lock Y, while agent B holds lock Y and waits for lock X. The scheduler detects these cycles automatically. When an acquire_lock call would create a circular wait in the wait-for graph, it returns a deadlock error with the cycle path instead of blocking forever. The agent can then release its held locks and retry.
Note: The agent prompt constrains agents to one lock at a time for simplicity. Multi-lock is available for advanced use cases where the agent is explicitly instructed to hold multiple locks.

​
Auto-release on Exit

When an agent session ends — whether it finishes successfully, hits an error, or times out — all of its locks are released automatically by the scheduler. You don’t need to worry about cleanup in error paths.

​
Example in SKILL.md

​
Configuration

​
See Also