DEV Community

giveitatry
giveitatry

Posted on

Running a TeamCity Agent as a systemd Service

#teamcity

Running a TeamCity agent as a system service ensures it continues working after logout and automatically starts on boot. This is the recommended production setup.

📁 Prerequisites

Make sure your TeamCity agent is installed in:

/opt/teamcity/bin/agent.sh
Enter fullscreen mode Exit fullscreen mode

👉 The agent.sh script must exist inside the bin directory:

/opt/teamcity/bin/agent.sh
Enter fullscreen mode Exit fullscreen mode

Also ensure it is executable:

chmod +x /opt/teamcity/bin/agent.sh
Enter fullscreen mode Exit fullscreen mode

⚙️ Create systemd service

Create the file:

sudo nano /etc/systemd/system/teamcity-agent.service
Enter fullscreen mode Exit fullscreen mode

Paste the following configuration:

[Unit]
Description=TeamCity Build Agent
After=network.target

[Service]
Type=oneshot
User=root
Group=root
WorkingDirectory=/opt/teamcity

ExecStart=/opt/teamcity/bin/agent.sh start
ExecStop=/opt/teamcity/bin/agent.sh stop

RemainAfterExit=yes
SuccessExitStatus=0 143

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

🚀 Enable and start the service

Reload systemd and start the agent:

sudo systemctl daemon-reload
sudo systemctl enable teamcity-agent
sudo systemctl start teamcity-agent
Enter fullscreen mode Exit fullscreen mode

🔍 Verify status 

systemctl status teamcity-agent
Enter fullscreen mode Exit fullscreen mode

Expected result:

Active: active (exited)
Enter fullscreen mode Exit fullscreen mode

This is normal for TeamCity agents when using Type=oneshot.

⚠️ Notes

  • The agent must be located in /opt/teamcity/bin/agent.sh
  • RemainAfterExit=yes is required so systemd considers the service active
  • SuccessExitStatus=143 prevents false failure detection
  • Using root works, but for production it's safer to use a dedicated user

Top comments (0)