tencent cloud

Tencent WorkBuddy Enterprise

DocumentationTencent WorkBuddy EnterpriseCodeBuddyCodeBuddy CodeReference DocumentationPrewarm Process

Prewarm Process

Download
Focus Mode
Font Size
Last updated: 2026-09-30 18:41:48
AI-Translated
Note:
Applies to: @tencent-ai/codebuddy-code (cbc / codebuddy)
The warm-up process lets cbc complete the cold start first and then suspend (load bundle → container initialization → authentication → product configuration → MCP discovery). After that, when woken up via local IPC, it only needs to bind the working directory to serve immediately. This is suitable for scenarios that require "starting sessions in seconds" (such as serve/acp gateways, session pools, and scheduler pre-warm-up).
Benefit: In local tests, the startup wait for a single session dropped from approximately 3.7s to ~1ms.
Note:
Disabled by default. It is enabled only when --prewarm is explicitly passed, without affecting any existing usage.

Quick and Easy to Use

1. Starting a Prewarm Process (Standby)

cbc --prewarm --prewarm-id pool1
The process completes the cold start and then suspends at the local IPC endpoint, waiting for commands without binding the working directory:
macOS / Linux: unix socket /tmp/codebuddy-prewarm-pool1.sock (permission 0600, current user only;
The socket directory can be overridden by the env variable CODEBUDDY_CODE_PREWARM_SOCKET_PATH).
Windows:named pipe \\\\.\\pipe\\codebuddy-prewarm-pool1
--prewarm-id can be omitted. By default, the process PID is used as the identifier.

2. Viewing / Waking Up (Lightweight Management Command cbc-prewarm)

cbc-prewarm is a lightweight, pure Node command with zero dependencies. It does not load the main program bundle and returns in milliseconds.
# List prewarmed processes found on the current machine
cbc-prewarm list

# Health Check
cbc-prewarm ping pool1

# Query status (idle / activating / active)
cbc-prewarm status pool1

# Wake Up: Bind to the Target Working Directory and Start the Service
cbc-prewarm activate pool1 --cwd /path/to/project -- --serve
Arguments after -- in activate are passed through to the awakened process (equivalent to a normal cbc <args>). After being awakened, the process chdirs to --cwd, enters the corresponding mode based on the passed-through arguments (such as --serve / --acp), and actively closes the IPC socket (one-time wake-up, after which it serves externally through its own service port).
--cwd is optional: when --cwd is omitted, the prewarmed process keeps the working directory from the cold start (no chdir and no cwd change broadcast). This is suitable for scenarios where the caller does not need to switch directories and only wants to reuse the prewarmed container. Pass --cwd only when you need to bind to a specific project directory.
No mode restrictions: the passed-through arguments can be any normal cbc arguments. Resident modes such as --serve and --acp take effect as-is, and the prewarmed process does not restrict or rewrite any mode. To run a resident service, pass --serve / --acp. If no resident mode flag is passed, the process follows the one-shot command path and exits after execution (headless and without a TTY).

External Program Integration (IPC Protocol)

To wake up a prewarmed process from your own program, connect directly to the local socket / pipe, send a single line of JSON (NDJSON, one message per line), and read a single line of JSON response.

Address Convention

macOS/Linux: <dir>/codebuddy-prewarm-<id>.sock (<dir> defaults to /tmp)
Windows     : \\\\.\\pipe\\codebuddy-prewarm-<id>
The default directory for the unix socket is /tmp. It can be overridden by the env variable CODEBUDDY_CODE_PREWARM_SOCKET_PATH (for example, when /tmp is mounted as noexec or read-only, or when the socket needs to be placed in a controlled directory). The process side and the client side read the same env variable to stay consistent. The Windows named pipe namespace has no directory concept and is not affected by this env variable.

Message

// Health Check
{ "cmd": "ping" }
// → { "ok": true, "cmd": "ping", "status": "idle", "pid": 12345 }

// Query status
{ "cmd": "status" }
// → { "ok": true, "status": "idle"|"activating"|"active", "cwd": "...", "endpoint": "..." }

// Wake Up (cwd is optional. If omitted, the cold-start cwd is retained. args are the parameters passed through to cbc.)
{ "cmd": "activate", "cwd": "/path/to/project", "args": ["--serve"], "sessionId": "optional" }
// → { "ok": true, "cmd": "activate", "status": "activating", "cwd": "..." }

// Wake up and wait for the ACP service to be ready (opt-in; recommended to use with --port 0)
{
  "cmd": "activate",
  "ackMode": "ready",
  "cwd": "/path/to/project",
  "args": ["--serve", "--port", "0"],
  "sessionId": "session-1"
}
// → Responds only after ACP /api/v1/acp initialization is complete:
// {
//   "ok": true,
//   "cmd": "activate",
//   "status": "active",
//   "pid": 12345,
//   "sessionId": "session-1",
//   "cwd": "/path/to/project",
//   "endpoint": "http://127.0.0.1:54321/api/v1/acp"
// }
activate can succeed only once. A repeated activate returns { ok: false, error: "already activated" }.
ackMode is omitted by default, preserving the backward-compatible immediate ACK: the IPC server returns status: "activating" as soon as it receives a request, which does not mean that the HTTP listener or ACP routes are already available. Hosts that need to hand the endpoint directly to downstream clients should explicitly pass "ackMode": "ready":
The child process uses --port 0 to have the kernel assign a contention-free port.
The response is delayed until the HTTP listener has started and ACP /api/v1/acp initialization is complete.
The ready response carries the actual non-zero port, the pid, and the sessionId returned as-is. The caller should verify all three.
After the ready ACK is flushed, the warm-up IPC is closed and cleaned up. Subsequent communication is switched to the returned ACP endpoint.
The caller should use a timeout window that covers the entire cold start. WorkBuddy waits 180 seconds by default. If the connection is disconnected early,
agent-cli does not terminate a serve process that is already ready on its own. The host should still reclaim processes that it cannot take over.

Node.js Example

const net = require('net');

function prewarmAddr(id) {
  if (process.platform === 'win32') {
    return `\\\\\\\\.\\\\pipe\\\\codebuddy-prewarm-${id}`;
  }
  const dir = (process.env.CODEBUDDY_CODE_PREWARM_SOCKET_PATH || '').trim() || '/tmp';
  return require('path').join(dir, `codebuddy-prewarm-${id}.sock`);
}

function activate(id, { cwd, args = [] }) {
  return new Promise((resolve, reject) => {
    const sock = net.connect(prewarmAddr(id), () => {
      sock.write(JSON.stringify({ cmd: 'activate', cwd, args }) + '\\n');
    });
    let buf = '';
    sock.on('data', d => {
      buf += d;
      const nl = buf.indexOf('\\n');
      if (nl >= 0) { sock.end(); resolve(JSON.parse(buf.slice(0, nl))); }
    });
    sock.on('error', reject);
  });
}

// Wake up pool1, bind the target directory, and start it in serve mode
const res = await activate('pool1', { cwd: '/Users/me/project-A', args: ['--serve'] });
console.log(res); // { ok: true, cmd: 'activate', status: 'activating', cwd: '...' }
The preceding example shows the default immediate ACK. To use the ACP-ready boundary, change the sent content to:
sock.write(JSON.stringify({
  cmd: 'activate',
  ackMode: 'ready',
  sessionId: 'session-1',
  cwd,
  args: ['--serve', '--port', '0'],
}) + '\\n');

Behavior and Constraints

One process, one session: each prewarmed process binds a working directory only once in its lifetime (at the moment of activation) and is discarded after use. To serve multiple directories, prewarm multiple processes with different --prewarm-id values. They are independent and do not affect each other.
Working directory isolation: after activation, the process runs chdir and broadcasts the cwd change. File watchers are automatically rebound, and project-level caches (settings, memory, skills, plugins, and product configurations) are automatically invalidated and rescanned, ensuring that stale configurations from the temporary directory used during prewarming are never read.
USER-level configuration sharing: user-level settings, authentication, and MCP under ~/.codebuddy/ are naturally shared across all prewarmed processes.
Security: the unix socket permission is tightened to 0600 (owner only) to prevent connection hijacking by other users on the same machine.
Exit cleanup: the socket is automatically cleaned up after a graceful exit (SIGINT/SIGTERM) or after activation completes. A socket left behind by SIGKILL is automatically overwritten the next time a process with the same id starts.

Configuration Method

Prewarm-related parameters can only be configured through CLI flags: --prewarm, --prewarm-id <id>, and --prewarm-force.
You can also override the unix socket directory by using the env variable:
env
Function
Default Value
CODEBUDDY_CODE_PREWARM_SOCKET_PATH
Customizes the unix socket storage directory (for example, /dev/abc/, with the trailing slash optional). The process side creates + the client side connects to read the same env. unix only; Windows named pipes are not affected.
/tmp

Related

CLI Parameter Reference: cli-reference.md

Previous Topic: HTTP API (Beta)Next Topic: Quick Start

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation