Download and Unzip the Agent

Oct 13, 2025 by talynt.org 39 views

Introduction

Setting up a self-hosted agent on MacOS can be a straightforward process, but it can become complicated when trying to minimize the permissions of the account used to run the agent. In this article, we will explore the steps to set up a self-hosted agent on MacOS with a non-admin account and troubleshoot common issues that may arise.

Describe Your Question

You want to set up a self-hosted agent on MacOS with a non-admin account, but you're facing issues with loading the LaunchAgent plist file. You've created a new user account, downloaded and configured the agent, and verified that the user has the necessary permissions.

Steps You've Taken

Create a New User Account

You've created a new user account called devops using the sysadminctl command.

sudo sysadminctl -addUser devops -fullName "Azure DevOps"

Download and Unzip the Agent

You've downloaded the agent using curl and unzipped it using tar.

curl -L -o myagent.tar.gz https://vstsagentpackage.azureedge.net/agent/4.252.0/vsts-agent-osx-x64-4.252.0.tar.gz
mkdir ~/myagent && cd ~/myagent
tar -xvf ~/myagent.tar.gz

Configure the Agent

You've configured the agent using the config.sh script.

./config.sh

Run the Agent Interactively

You've run the agent interactively using the run.sh script.

./run.sh

Install the Service

You've installed the service using the svc.sh script.

./svc.sh install

Troubleshoot the Issue

You're facing an issue with loading the LaunchAgent plist file, and you've verified that the user has the necessary permissions.

Versions

Agent Version: vsts-agent-osx-x64-4.252.0
OS Version: 15.3.1

Environment Type

Self-Hosted

Azure DevOps Server Type

dev.azure.com (formerly visualstudio.com)

Operation System

MacOS 15.3.1

Version Control System

No response

Azure DevOps Server Version (if applicable)

No response

Troubleshooting the Issue

When you try to start the service, you receive the following error:

Failed: failed to load /Users/devops/Library/LaunchAgents/vsts.agent.DevOps.DevOps-Mac.DevOps-Mac-mini.plist

You've verified that the devops user has read and write permissions on the plist file:

-rw-r--r--  1 devops  staff  994 Mar 12 21:41 /Users/devops/Library/LaunchAgents/vsts.agent.DevOps.DevOps-Mac.DevOps-Mac-mini.plist

To troubleshoot this issue, let's try the following steps:

Verify the plist File

Make sure the plist file is correctly formatted and contains the necessary information.

Check the LaunchAgent Directory

Verify that the LaunchAgent directory exists and is writable by the devops user.

Check the Agent Configuration

Verify that the agent configuration is correct and that the plist file is being generated correctly.

Check the System Logs

Check the system logs for any errors related to the LaunchAgent plist file.

Check the Agent Logs

Check the agent logs for any errors related to the LaunchAgent plist file.

Conclusion

Setting up a self-hosted agent on MacOS with a non-admin account can be a challenging task, but with the right troubleshooting steps, you can resolve common issues. In this article, we've explored the steps to set up a self-hosted agent on MacOS with a non-admin account and troubleshoot common issues that may arise. By following these steps, you can successfully set up a self-hosted agent on MacOS with a non-admin account.

Additional Resources

Setting up a Self-Hosted Agent on Windows
Setting up a Self-Hosted Agent on Linux
Q&A: Running a Self-Hosted Agent with a Non-Admin Account on MacOS ====================================================================

Q: What is a self-hosted agent?

A: A self-hosted agent is a software agent that is installed and run on a local machine, rather than on a cloud-based platform. This allows you to run your build and deployment pipelines on your own infrastructure.

Q: Why do I need to run a self-hosted agent with a non-admin account?

A: Running a self-hosted agent with a non-admin account is a security best practice that helps to minimize the risk of unauthorized access to your system. By running the agent with a non-admin account, you can ensure that the agent has only the necessary permissions to perform its tasks.

Q: What are the benefits of running a self-hosted agent with a non-admin account?

A: The benefits of running a self-hosted agent with a non-admin account include:

Improved security: By running the agent with a non-admin account, you can minimize the risk of unauthorized access to your system.
Reduced risk of data breaches: By limiting the permissions of the agent, you can reduce the risk of data breaches.
Improved compliance: Running a self-hosted agent with a non-admin account can help you to meet compliance requirements.

Q: How do I set up a self-hosted agent on MacOS with a non-admin account?

A: To set up a self-hosted agent on MacOS with a non-admin account, follow these steps:

Create a new user account with limited permissions.
Download and install the agent.
Configure the agent to run with the non-admin account.
Verify that the agent is running correctly.

Q: What are some common issues that I may encounter when running a self-hosted agent with a non-admin account?

A: Some common issues that you may encounter when running a self-hosted agent with a non-admin account include:

Permission errors: The agent may not have the necessary permissions to perform its tasks.
Configuration errors: The agent may not be configured correctly to run with the non-admin account.
System errors: The agent may encounter system errors that prevent it from running correctly.

Q: How do I troubleshoot issues with my self-hosted agent on MacOS with a non-admin account?

A: To troubleshoot issues with your self-hosted agent on MacOS with a non-admin account, follow these steps:

Check the agent logs for errors.
Verify that the agent has the necessary permissions.
Check the system logs for errors.
Consult the agent documentation for troubleshooting tips.

Q: What are some best practices for running a self-hosted agent with a non-admin account on MacOS?

A: Some best practices for running a self-hosted agent with a non-admin account on MacOS include:

Use a non-admin account to run the agent.
Limit the permissions of the agent to only what is necessary.
Verify that the agent is running correctly.
Monitor the agent logs for errors.
Consult the agent documentation for best practices.

Q: Can I run a self-hosted agent with a non-admin account on other operating systems?

A: Yes, you can run a self-hosted agent with a non-admin account on other operating systems, including Windows and Linux. However, the specific steps and best practices may vary depending on the operating system.

Q: Where can I find more information about running a self-hosted agent with a non-admin account on MacOS?

A: You can find more information about running a self-hosted agent with a non-admin account on MacOS in the following resources:

Azure DevOps documentation: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-osx?view=azure-devops
MacOS documentation: https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/MacOSX_Development/ManagingApplicationInformation/ManagingApplicationInformation.html