How to Set Idle Timeout for OfficeCLI Resident Mode: Environment Variables and RPC Methods

Set the OFFICECLI_RESIDENT_IDLE_SECONDS environment variable (1–86,400 seconds) before launching the resident, or call ResidentClient.SendSetIdleTimeout (or the __set-idle-timeout__ RPC) to adjust the timeout dynamically while the process is running.

OfficeCLI maintains a resident process—a long-lived background server—for each opened Office document to enable fast subsequent operations. By default, this process shuts down after 12 minutes of inactivity, but you can customize this idle timeout to balance resource usage against responsiveness. This guide explains how to set idle timeout for OfficeCLI resident mode using environment variables or programmatic RPC calls based on the iOfficeAI/OfficeCLI source code.

Understanding the Resident Idle Timeout Mechanism

The resident mode keeps a document loaded in memory to eliminate cold-start delays. Two cancellation token sources govern the lifecycle: _idleCts (handles shutdown) and _autosaveCts (handles periodic saves). Both timers reset on every command via ResetIdleTimer(). When modifying the timeout, the new value takes effect immediately without waiting for the previous delay to expire.

Method 1: Configure via Environment Variable

The resident reads the initial timeout once during startup from the OFFICECLI_RESIDENT_IDLE_SECONDS environment variable.

In src/officecli/ResidentServer.cs, the ResolveIdleTimeout method (lines 99–108) parses this variable. If the value is a valid integer between 1 and 86,400 (24 hours), it becomes the initial timeout; otherwise, the system defaults to 720 seconds (12 minutes).

# Set timeout to 5 minutes (300 seconds) before starting the resident

export OFFICECLI_RESIDENT_IDLE_SECONDS=300
officecli create mydoc.docx --resident

Method 2: Set Timeout Dynamically via RPC

After a resident starts, you can change the timeout without restarting the process by sending the __set-idle-timeout__ RPC command. The resident validates the request in ResidentServer.TrySetIdleTimeout (lines 176–183) and updates the internal tick counter immediately. The RPC handler resides at lines 578–587 in src/officecli/ResidentServer.cs.

Using the C# ResidentClient

The ResidentClient.SendSetIdleTimeout method in src/officecli/ResidentClient.cs (lines 26–44) wraps this RPC for .NET applications.

using OfficeCli;

// Update timeout to 30 minutes (1800 seconds) for an existing resident
bool success = ResidentClient.SendSetIdleTimeout(@"C:\Docs\mydoc.docx", 1800);
Console.WriteLine(success ? "Timeout updated" : "Update failed");

Using the Python SDK

The Python SDK exposes the same functionality through low-level RPC calls:

from officecli import OfficeCli

cli = OfficeCli()
cli.open("mydoc.docx")

# Set idle timeout to 10 minutes

cli._rpc(cli._ping, {
    "Command": "__set-idle-timeout__", 
    "Args": {"seconds": "600"}
}, timeout=5)

Using the Node.js SDK

Similarly, the Node.js SDK uses the __set-idle-timeout__ command:

const { OfficeCLI } = require('officecli');

(async () => {
  const cli = new OfficeCLI();
  await cli.open('mydoc.docx');
  await cli._rpc(cli._ping, {
    Command: '__set-idle-timeout__',
    Args: { seconds: '900' }  // 15 minutes
  });
})();

Valid Ranges and Special Behaviors

Valid values for the idle timeout range from 1 second (MinIdleSeconds) to 86,400 seconds (24 hours) (MaxIdleSeconds). The system explicitly rejects 0 seconds to prevent a busy-spin watchdog condition.

Be aware of the dynamic upgrade behavior: when you create a document with officecli create, the resident starts with a conservative 60-second timeout. When you subsequently open that document with officecli open, the CLI automatically upgrades the timeout to the standard 12 minutes (or your custom value) via ResidentClient.SendSetIdleTimeout.

Summary

• Set the OFFICECLI_RESIDENT_IDLE_SECONDS environment variable before starting the resident to define the initial timeout.
• Use ResidentClient.SendSetIdleTimeout (C#) or the __set-idle-timeout__ RPC (Python/Node.js) to modify the timeout of a running resident.
• Valid range is 1–86,400 seconds; 0 is disallowed; default is 720 seconds (12 minutes).
• Changes take effect immediately without waiting for the previous timer to expire.
• The resident implementation resides in src/officecli/ResidentServer.cs and client helpers in src/officecli/ResidentClient.cs.

Frequently Asked Questions

What is the default idle timeout for OfficeCLI resident mode?

The default idle timeout is 720 seconds (12 minutes). This value applies when the OFFICECLI_RESIDENT_IDLE_SECONDS environment variable is unset or contains an invalid value, as implemented in ResidentServer.ResolveIdleTimeout.

Can I set the idle timeout to zero to keep the resident running indefinitely?

No. Values of 0 seconds are explicitly rejected because they would cause the idle watchdog to busy-spin. The minimum valid timeout is 1 second, and the maximum is 86,400 seconds (24 hours). If you need the resident to persist indefinitely, set the timeout to 24 hours and ensure periodic activity.

Why does the resident start with a 60-second timeout when I create a document?

When you create a new document using officecli create --resident, the process starts with a conservative 60-second timeout to prevent resource waste if the operation fails. The timeout automatically upgrades to the standard 12 minutes (or your custom value) when you subsequently execute officecli open on that file, which calls SendSetIdleTimeout via RPC.

How do I verify the current idle timeout setting?

OfficeCLI does not expose a direct getter for the current timeout value. Check the environment variable you set before starting the resident, or track the value you last sent via ResidentClient.SendSetIdleTimeout or the __set-idle-timeout__ RPC in your application code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}