Standalone Agent Binaries

Crow publishes pre-built agent binaries for macOS, Linux and Windows. They exist for one purpose only: running an agent with the local backend, which executes pipeline commands directly on the host instead of in a container.

This is not a general installation method

Reach for a binary agent only if you own the host, control who can push to the repositories it builds, and understand the trade-offs below. For every other case, run the agent as a container: see Docker Compose, Helm or Ansible.

The local backend is not a container backend with a different name:

• No isolation from the host. Pipeline commands run as the agent’s user, with that user’s filesystem, network and credential access. A pipeline can read the agent’s own config and any secret on the host.
• No sandboxing outside macOS. CROW_BACKEND_LOCAL_SANDBOX_LEVEL is implemented with macOS sandbox-exec and is a no-op on Linux and Windows. On those platforms there is no isolation at all, at any setting.
• No plugins. Plugins are container images, and the local backend resolves image: with a PATH lookup instead. A plugin only runs if a binary of that name happens to be installed on the host.
• No service containers. services: are resolved the same way and need the service to already exist as a host binary.
• The host is the build environment. There is no per-pipeline clean slate: pipelines see whatever toolchain versions the host has, and leftovers from one pipeline are visible to the next.

The server itself is container-only. These binaries do not let you run a Crow server outside of a container.

Installation

The snippets below resolve the newest release through the forge API. Set TAG to something like v6.4.0 instead to pin a specific release, and ARCH to your architecture.

macOS

Available for amd64 and arm64.

# resolve the latest release tag
export TAG=$(curl -s https://codefloe.com/api/v1/repos/crowci/crow/releases/latest | jq -r .tag_name)
export ARCH=arm64
curl -LO https://codefloe.com/crowci/crow/releases/download/$TAG/crow-agent_darwin_$ARCH.tar.gz

# Extract the archive
tar -xzf crow-agent_darwin_*.tar.gz

# Move to system path
sudo mv crow-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/crow-agent

# Verify installation
crow-agent --version

Linux

Available for amd64 and arm64.

# resolve the latest release tag
export TAG=$(curl -s https://codefloe.com/api/v1/repos/crowci/crow/releases/latest | jq -r .tag_name)
export ARCH=amd64
curl -LO https://codefloe.com/crowci/crow/releases/download/$TAG/crow-agent_linux_$ARCH.tar.gz

# Extract the archive
tar -xzf crow-agent_linux_*.tar.gz

# Move to system path
sudo mv crow-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/crow-agent

# Verify installation
crow-agent --version

Caution

Read the box at the top of this page before running this agent on Linux. Nothing separates a pipeline from the rest of the machine, so treat every repository the agent builds as having shell access to that host.

Windows

crow-agent_windows_amd64.zip is published for the same reasons, plus the autoscaler, which downloads it onto Windows VMs. Windows agents normally run the docker backend rather than the local one: see Windows Agents.

Why no systemd units, .deb or .rpm packages

Only plain tarballs are published, and that is deliberate.

Packaging the agent for a distribution, or shipping a ready-made systemd unit, presents host installation as an equally supported alternative to the container agent. It is not: everything in the box at the top of this page still applies, and the resulting agent is markedly less capable and less contained than a container one. Users who install from a distribution package reasonably expect the two to be interchangeable, and then hit the missing plugin and isolation guarantees later, in production.

If you need the agent supervised on Linux, wire the binary into whatever service manager you already run. Give it its own unprivileged user, keep that user away from anything the pipelines should not reach, and do not run it as root.

See #1406 for the discussion behind this.

Running as a System Service

macOS (launchd)

Running the agent as a system service on macOS uses launchd with a Launch Daemon or Launch Agent.

Create the plist file using your preferred text editor:

sudo nano /Library/LaunchDaemons/crowci.agent.plist

Paste the following content (update CROW_SERVER and CROW_AGENT_SECRET with your values):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>crowci.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/crow-agent</string>
    </array>

    <key>EnvironmentVariables</key>
    <dict>
        <key>CROW_SERVER</key>
        <string>grpc.your-server.com:443</string>
        <key>CROW_GRPC_SECURE</key>
        <string>true</string>
        <key>CROW_AGENT_SECRET</key>
        <string>your-secret-token</string>
        <key>CROW_BACKEND</key>
        <string>local</string>
        <key>CROW_BACKEND_LOCAL_SANDBOX_LEVEL</key>
        <string>standard</string>
        <key>CROW_AGENT_CONFIG_FILE</key>
        <string>/usr/local/var/crow-agent/config.yml</string>
    </dict>

    <key>StandardOutPath</key>
    <string>/usr/local/var/log/crow-agent.log</string>

    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/crow-agent-error.log</string>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/usr/local/var/crow-agent</string>
</dict>
</plist>

Note

For remote/public servers: The example above assumes a secure gRPC connection (typical for remote agents).

• CROW_SERVER: The gRPC endpoint as <host>:<port> (typically :443 for a TLS-terminating proxy)
• CROW_GRPC_SECURE: Set to true for TLS connections

For local servers: If connecting to a server on the same network without TLS, use:

<key>CROW_SERVER</key>
<string>your-server-ip:9000</string>

And remove the CROW_GRPC_SECURE key.

After saving the file, validate it:

plutil -lint /Library/LaunchDaemons/crowci.agent.plist

Set up and start the service:

# Create working directories
sudo mkdir -p /usr/local/var/crow-agent /usr/local/var/log

# Set proper permissions on the plist file
sudo chown root:wheel /Library/LaunchDaemons/crowci.agent.plist
sudo chmod 644 /Library/LaunchDaemons/crowci.agent.plist

# Load and start the service (bootstrap will start it automatically)
sudo launchctl bootstrap system /Library/LaunchDaemons/crowci.agent.plist

# Verify the service is running
sudo launchctl list | grep crowci

# View logs
tail -f /usr/local/var/log/crow-agent.log
tail -f /usr/local/var/log/crow-agent-error.log

Service Management (macOS)

# Stop the service
sudo launchctl kickstart -k system/crowci.agent

# Restart the service
sudo launchctl kickstart -kp system/crowci.agent

# Unload/remove the service
sudo launchctl bootout system /Library/LaunchDaemons/crowci.agent.plist

# Check service status
sudo launchctl print system/crowci.agent

Note

When running the agent on macOS with the local backend, you should enable process isolation using the built-in sandbox-exec utility.

macOS Sandbox Security Levels

The CROW_BACKEND_LOCAL_SANDBOX_LEVEL environment variable controls process isolation on macOS:

none (default)

No sandboxing. Workflows run with full system access. Use only in trusted environments.

standard (recommended)

Balanced security profile suitable for most CI/CD workloads. This profile:

Allowed:

• ✅ Network access (for package downloads, git operations, API calls)
• ✅ Reading system libraries, tools, and executables
• ✅ Full read/write access to workflow directories (/tmp/crow-local-*)
• ✅ Executing binaries from standard paths (/usr/bin, /usr/local/bin, etc.)
• ✅ Process management (fork, signal, IPC)
• ✅ Device file access (/dev/null, /dev/random, etc.)

Denied:

• ❌ Reading sensitive system files (/etc/passwd, /etc/sudoers, etc.)
• ❌ Reading macOS user database (/var/db/dslocal/nodes/Default/users/)
• ❌ Accessing user directories (Documents, Desktop, Pictures, Downloads)
• ❌ Reading SSH private keys (~/.ssh/id_*)
• ❌ Privilege escalation (sudo is blocked)
• ❌ Writing outside workflow directories

This profile allows typical CI/CD operations (building, testing, deploying) while preventing:

• Credential theft (SSH keys, passwords)
• Privilege escalation
• Access to personal files
• System configuration changes

strict

Maximum security with minimal permissions. Denies network access and restricts file operations to workflow directories only. Use for highly sensitive workloads requiring maximum isolation.