Monitor and troubleshoot self-hosted workers

The monitoring calls on this page run from your monitoring or operations tooling, authenticated with your Claude API key. The worker helpers handle the claim and keep-alive loop, so you don't call those endpoints directly.

Read queue depth

client.beta.environments.work.stats() returns the queue state for an environment:

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Stop a session gracefully

Use client.beta.environments.work.stop() to ask the worker handling a specific session to shut it down.

By default the work item moves to stopping. The worker notices on its next lease heartbeat, cancels the session's in-flight tool call, and confirms the shutdown. The work item then becomes stopped.

Pass force=True to mark the work item stopped immediately instead of waiting for the worker's confirmation.

Because these calls run from your operations tooling rather than the worker host, ANTHROPIC_WORK_ID isn't set automatically. Set it to the target work item's ID before running the following examples. To find a work item's ID, list the environment's work items through the Environments Work endpoints.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Stop workers gracefully

A worker that is cancelled while a session runs stops its in-flight work before it exits. If the session has memory stores attached, the worker skips the final sync but still uploads changed files and removes the store directories.

A killed process runs no teardown. To stop a worker cleanly:

1. Make sure SIGTERM and SIGINT cancel the worker. How depends on the worker:

   Worker	What to do
   ant CLI	Nothing. The CLI handles both signals itself: it cancels any in-flight tool call, posts its error result, and releases the work item.
   SDK worker that is its own process	EnvironmentWorker installs no signal handlers. Cancel the worker from a signal handler, as the standalone worker examples do.
   SDK worker inside a webhook server	Cancel the worker from the server's own shutdown hook, as the webhook examples do. The worker must not take over the server's signals.

2. Stop the worker with SIGTERM, and allow at least 30 seconds before any hard kill. The final upload can take that long. Docker sends SIGKILL 10 seconds after the stop signal by default. Raise that limit with --stop-timeout on docker run, or with your orchestrator's termination grace period.

If a worker is killed before its teardown runs, any memory edits that had not synced are lost. On a long-lived host, also remove the leftover store directory under /mnt/memory/ before the next session that attaches that store. A sandbox that serves one session and is then discarded needs no cleanup.

Troubleshooting

The worker doesn't connect

If workers_polling stays at 0, the worker isn't reaching the queue. Confirm that ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID are set on the worker host.

A session stays queued

No worker is claiming work. A queued session waits rather than failing. Check workers_polling and depth in Read queue depth.

Memory stores fail to mount

The worker logs mount and background sync failures rather than reporting them to the session. Only read-only refusals reach the agent, as tool errors (see Read-only stores and conflicts).

If the worker cannot mount a memory store when it claims a session, it fails the work item. The session emits no error event and stays idle.

A custom tool call never returns

If the session sits paused with a requires_action stop reason, no worker or client serves that tool. See Serve a custom tool.

A wrapped MCP tool call hangs

Without a timeout on the MCP client, a hung call to a wrapped MCP server becomes an error tool result only when a backstop fires: