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

ToolDescription
acquire_lockAcquire an exclusive lock. Fails if another instance holds it.
release_lockRelease a lock. Only the holder can release.
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:
PatternExample
github://owner/repo/issues/numbergithub://acme/app/issues/42
github://owner/repo/pr/numbergithub://acme/app/pr/17
deploy://service-namedeploy://api-prod

​
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. 
# Example deadlock cycle:
# Agent A holds "github://acme/app/pr/10", wants "deploy://api-prod"
# Agent B holds "deploy://api-prod", wants "github://acme/app/pr/10"
# → acquire_lock returns: Deadlock detected
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

## Workflow

1. List open issues labeled "agent" in repos from `<agent-config>`
2. For each issue:
   - Use `acquire_lock` with the issue URI (e.g. "github://owner/repo/issues/123")
   - If the lock fails, skip this issue — another instance is handling it
   - Clone the repo, create a branch, implement the fix
   - Open a PR and link it to the issue
   - Use `release_lock` to release the issue lock

​
Configuration

SettingLocationDefaultDescription
resourceLockTimeoutconfig.toml1800 (30 min)Default TTL for locks in seconds

​
See Also