# How the Jenkins Remoting System Enables Distributed Agent Communication

> Understand the Jenkins remoting system for distributed agent communication. Discover how Jenkins controllers execute code on remote agents via a custom TCP protocol and Channel abstraction.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: internals
- Published: 2026-06-19

---

**Jenkins remoting is the core bi-directional communication layer that allows a Jenkins controller to execute code on remote agents through a custom TCP-based protocol, lightweight Java serialization, and a flexible Channel abstraction.**

The Jenkins remoting system serves as the foundation for distributed builds in the `jenkinsci/jenkins` repository, enabling the controller to orchestrate jobs across multiple agent nodes via the `jenkins-remoting` library. This system handles everything from remote procedure calls to file streaming across the network, providing a single multiplexed channel for all controller-agent interactions.

## Architecture of the Jenkins Remoting System

### Channel Abstraction and Bidirectional Communication

At the heart of the system lies the `Channel` class, which establishes a full-duplex communication tunnel over a single socket connection. According to the source code in [`core/src/main/java/jenkins/slaves/RemotingVersionInfo.java`](https://github.com/jenkinsci/jenkins/blob/main/core/src/main/java/jenkins/slaves/RemotingVersionInfo.java), the system supports connections over plain TCP, SSH tunnels, or WebSocket transports. Once established, this channel allows the controller to invoke callables on the agent while simultaneously receiving console output, file streams, and diagnostic data from the remote side.

### Version Negotiation and Compatibility

When a channel initializes, both endpoints exchange version information defined in `core/src/filter/resources/jenkins/slaves/remoting-info.properties`. The `RemotingVersionInfo` class reads these properties to enforce a minimum supported version check, ensuring that API compatibility exists between controller and agent. This negotiation prevents connection failures by verifying that the remote side meets or exceeds `MINIMUM_SUPPORTED_VERSION` before executing any operations.

### Remote Procedure Calls and File Transfer

The controller executes remote code by sending `Callable` objects—such as `ControllerToAgentCallable`—which deserialize and execute on the agent side. Results or exceptions marshal back across the same channel. For file operations, `FilePath` methods like `copyTo()`, `copyFrom()`, `write()`, and `read()` leverage the underlying channel to stream bytes without creating additional sockets, multiplexing all traffic through the established connection.

## Connection Lifecycle and Handshake Process

1. **Agent Launch**: The controller initiates the connection via JNLP, SSH, or a custom launcher, starting the `remoting.jar` on the agent side.

2. **Channel Establishment**: Depending on the launcher configuration, either the agent opens a socket to the controller or the controller connects outbound, creating a `Channel` object on both ends.

3. **Version Handshake**: Both sides read `remoting-info.properties` and verify that the remote version meets or exceeds `MINIMUM_SUPPORTED_VERSION`. Mismatches abort the connection with a descriptive error.

4. **Operational Phase**: The controller invokes `Callable` instances, streams files, and requests diagnostics through `RemotingDiagnostics`, with all traffic multiplexed over the single channel.

5. **Graceful Shutdown**: When builds complete or the agent goes offline, the channel closes cleanly, releasing all associated resources.

## Implementing Remote Operations in Jenkins Core

Developers interact with the remoting system through the `VirtualChannel` interface and `Callable` implementations. The following example demonstrates executing remote code and performing file operations:

```java
import hudson.remoting.VirtualChannel;
import hudson.remoting.Callable;
import jenkins.model.Jenkins;
import hudson.FilePath;
import java.io.IOException;

// Obtain the agent's channel (returns null if offline)
VirtualChannel channel = myAgent.getChannel();

// Define a Callable to execute on the remote agent
Callable<String, IOException> getHostname = new Callable<>() {
    @Override
    public String call() throws IOException {
        return java.net.InetAddress.getLocalHost().getHostName();
    }
};

// Execute remotely and retrieve the result
String hostname = channel.call(getHostname);
System.out.println("Agent hostname: " + hostname);

// Use FilePath to write via the same channel
FilePath workspace = myAgent.getWorkspace();
workspace.child("hello.txt").write("Hello from the controller!", "UTF-8");

```

The `channel.call()` method implements the RPC mechanism, while `FilePath` operations automatically handle serialization and streaming across the remoting channel.

## Work Directory Management and Diagnostics

The `RemotingWorkDirSettings` class in [`core/src/main/java/jenkins/slaves/RemotingWorkDirSettings.java`](https://github.com/jenkinsci/jenkins/blob/main/core/src/main/java/jenkins/slaves/RemotingWorkDirSettings.java) configures the agent's temporary file location, ensuring compatibility with the channel's virtual file system. For troubleshooting, `RemotingDiagnostics` provides methods to query remote health, capture thread dumps, and inspect class-loader status, all executing across the established channel.

## Summary

- The Jenkins remoting system provides a bi-directional communication layer between controller and agents through the `jenkins-remoting` library.
- A single `Channel` object multiplexes RPCs, file transfers, and diagnostics over one TCP socket, supporting TCP, SSH, or WebSocket transports.
- Version negotiation via `RemotingVersionInfo` and `remoting-info.properties` ensures backward compatibility by enforcing `MINIMUM_SUPPORTED_VERSION` checks during handshake.
- Remote execution relies on `Callable` objects serialized across the channel, while `FilePath` handles streaming file operations without additional connections.
- Connection lifecycle management includes agent launch, version handshake, operational multiplexing, and graceful shutdown.

## Frequently Asked Questions

### What is the Jenkins remoting system used for?

The Jenkins remoting system enables distributed builds by allowing the controller to communicate with remote agents. It handles remote procedure calls, file transfers, console output streaming, and diagnostic commands through a single bi-directional channel, abstracting network complexity from build operations.

### How does Jenkins ensure compatibility between controller and agent versions?

During the initial handshake, both sides exchange version information from `remoting-info.properties` via `RemotingVersionInfo`. The system verifies that the remote version meets or exceeds `MINIMUM_SUPPORTED_VERSION`, aborting the connection if compatibility requirements are not satisfied.

### Can the remoting channel operate over secure connections?

Yes, the channel supports TLS encryption when using SSH-based launchers or explicit SSL configurations. The protocol operates over TCP, SSH tunnels, or WebSocket connections, allowing administrators to secure agent-controller communication according to their network policies.

### What happens when an agent's channel goes offline?

When a channel closes—either gracefully or due to network failure—all pending `Callable` operations terminate, and the controller marks the agent as offline. File operations and remote executions will fail with `IOException` until the agent reconnects and re-establishes the channel.