Deploy Jenkins Agent

Deploy and Host a Jenkins Inbound Agent on Railway

A Jenkins inbound agent is a worker process that connects out to a Jenkins controller and executes build jobs on its behalf. Unlike an SSH-launched agent, the connection is initiated by the agent itself, making it a natural fit for containerized environments like Railway where you don't want to expose inbound access to the worker.

About Hosting a Jenkins Agent

An inbound agent needs three things to run: the URL of your Jenkins controller, the agent name registered on that controller, and a secret generated by the controller for that agent. Once connected, it stays idle until the controller assigns it a build, executes the job, and reports results back. Because the agent dials out rather than accepting inbound connections, Railway can host it without any special network configuration on the agent side, you just need the controller reachable from it.

Common Use Cases

• Running build jobs isolated from the Jenkins controller for better resource separation and security
• Scaling build capacity horizontally by adding more agent instances
• Running builds with a specific JDK, OS, or toolchain different from the controller's environment
• Isolating untrusted or resource-heavy jobs away from the controller process

Dependencies for Jenkins Agent Hosting

• A running Jenkins controller (see the Jenkins template)
• An agent name and secret generated from the controller (Manage Jenkins → Nodes → New Node)

Implementation Details

This template deploys the official jenkins/inbound-agent image, configured with three environment variables: JENKINS_AGENT_NAME, JENKINS_SECRET, and JENKINS_URL. If you need a specific JDK for your builds, pin the image tag accordingly (e.g. jenkins/inbound-agent:jdk21) rather than relying on the default. The JDK the agent runs on is independent of the JDK your build jobs actually compile or run against, so pick agent images with your job's toolchain in mind, or install additional JDKs as build tools.

Agent Setup

Jenkins Node Setup

Follow these steps to create a node in your Jenkins instance.

Setup the agent on Jenkins

1. Go to your Jenkins dashboard.
2. Go to the Manage Jenkins option in the main menu.
3. Go to Nodes under System Configuration.
4. Go to New Node in the side menu.
5. Fill in the Node (agent) name and select the type (e.g. Name: agent1, Type: Permanent Agent).
6. Fill in the remaining fields, such as remote root directory, labels, and number of executors:
   • Remote root directory should be set to /home/jenkins/agent
   • Launch method should be set to Launch agent by connecting it to the controller
7. Press Save. The agent1 node will be registered but offline for now.
8. Click on the new agent.
9. You should now see the secret used to configure the template below.

Template configuration

1. Set the JENKINS_AGENT_NAME environment variable to the agent name you selected above.
2. Set the JENKINS_SECRET environment variable to the secret generated above.
3. Set the JENKINS_URL environment variable to the URL of your Jenkins instance. If using my Jenkins Template, this should be set to http://${{Jenkins.JENKINS_PRIVATE_URL}}:${{Jenkins.JENKINS_PRIVATE_PORT}}.
4. Deploy it, and it should auto-connect to your Jenkins instance.

Why Deploy a Jenkins Agent on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying a Jenkins agent on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.