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

> Learn how to set idle timeout for OfficeCLI resident mode using environment variables like OFFICECLI_RESIDENT_IDLE_SECONDS or RPC methods for dynamic adjustments. Maximize control over your CLI sessions.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-09

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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)**.

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs).

### Using the C# ResidentClient

The `ResidentClient.SendSetIdleTimeout` method in [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs) (lines 26–44) wraps this RPC for .NET applications.

```csharp
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:

```python
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:

```javascript
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) and client helpers in [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.