Skip to content
UnboundBytes

Agent Installation

import { Steps, Tabs, TabItem, Aside, Card, CardGrid } from ‘@astrojs/starlight/components’;

Installing the UnboundBytes Agent

Section titled “Installing the UnboundBytes Agent”

The UnboundBytes Agent is a lightweight daemon that connects your server to the UnboundBytes control plane. Installation takes about 5 minutes.

Section titled “Quick Install (Recommended)”

The easiest way to install the agent is with the one-line installer:

Terminal window
curl -fsSL https://get.unboundbytes.com/agent | bash

This script:

  • Detects your OS and architecture
  • Downloads the latest agent binary
  • Verifies the download (SHA256 checksum)
  • Installs to /usr/local/bin/unboundbytes-agent
  • Optionally creates a systemd service for auto-start

That’s it! The installer guides you through each step.

Manual Installation

Section titled “Manual Installation”

If the quick installer doesn’t work for your environment, you can install manually:

  1. Detect your platform

    Terminal window
    # Check architecture
    uname -m
    # Output: x86_64 or aarch64
    

    # Check OS
    uname -s
    # Output: Linux or Darwin

  2. Download the agent binary

    ```bash curl -LO https://releases.unboundbytes.com/agent/latest/unboundbytes-agent-linux-x86_64.tar.gz ``` ```bash curl -LO https://releases.unboundbytes.com/agent/latest/unboundbytes-agent-linux-aarch64.tar.gz ``` ```bash curl -LO https://releases.unboundbytes.com/agent/latest/unboundbytes-agent-darwin-x86_64.tar.gz ``` ```bash curl -LO https://releases.unboundbytes.com/agent/latest/unboundbytes-agent-darwin-aarch64.tar.gz ```

  3. Extract and install

    Terminal window
    # Extract the archive
    tar -xzf unboundbytes-agent-*.tar.gz
    

    # Install to /usr/local/bin
    sudo mv unboundbytes-agent /usr/local/bin/
    sudo chmod +x /usr/local/bin/unboundbytes-agent
    

    # Verify installation
    unboundbytes-agent --version

  4. Create systemd service (Linux only)

    ```bash sudo tee /etc/systemd/system/unboundbytes-agent.service << 'EOF' [Unit] Description=UnboundBytes Agent After=network-online.target docker.service Wants=network-online.target docker.service 
    [Service]
    Type=simple
    User=root
    ExecStart=/usr/local/bin/unboundbytes-agent
    Restart=always
    RestartSec=10
    Environment=RUST_LOG=info
    StandardOutput=journal
    StandardError=journal
    

    [Install]
    WantedBy=multi-user.target
    EOF
    ```
     ```bash sudo tee /etc/systemd/system/unboundbytes-agent.service << 'EOF' [Unit] Description=UnboundBytes Agent After=network-online.target docker.service Wants=network-online.target docker.service 
    [Service]
    Type=simple
    ExecStart=/usr/local/bin/unboundbytes-agent
    Restart=always
    RestartSec=10
    Environment=RUST_LOG=info
    StandardOutput=journal
    StandardError=journal
    

    [Install]
    WantedBy=multi-user.target
    EOF
    ```

  5. Enable and start the service

    Terminal window
    sudo systemctl daemon-reload
    sudo systemctl enable unboundbytes-agent
    sudo systemctl start unboundbytes-agent

  6. Verify the agent is running

    Terminal window
    sudo systemctl status unboundbytes-agent

Post-Installation Setup

Section titled “Post-Installation Setup”

1. Check Agent Status

Section titled “1. Check Agent Status”

Verify the agent started successfully:

Terminal window
# Check systemd status
sudo systemctl status unboundbytes-agent


# View recent logs
sudo journalctl -u unboundbytes-agent -n 20 -f


# Expected output
# Jan 24 10:30:00 myserver unboundbytes-agent[1234]: Starting agent v2.1.0
# Jan 24 10:30:01 myserver unboundbytes-agent[1234]: Connecting to orchestrator...
# Jan 24 10:30:02 myserver unboundbytes-agent[1234]: Device pairing code: ABC-123

2. Pair Your Device

Section titled “2. Pair Your Device”

The agent prints a pairing code on first start. You’ll use this to connect your server to the portal:

  1. Get the pairing code

    If the agent is running as a service, check the logs:

    Terminal window
    sudo journalctl -u unboundbytes-agent -n 5

    Look for a line like: Device pairing code: ABC-123-DEF

  2. Open the UnboundBytes Portal

    Visit https://portal.unboundbytes.com and sign in to your account

  3. Navigate to Devices

    Click Devices in the left sidebar

  4. Add a Device

    Click Pair Device and paste or enter your pairing code

  5. Confirm the pairing

    The agent will verify the code and your device will appear as Online

3. Verify Docker/Podman

Section titled “3. Verify Docker/Podman”

The agent needs Docker or Podman to run apps. Verify it’s working:

Terminal window
# Check Docker
docker ps


# If you get a permission error, add your user to the docker group
sudo usermod -aG docker $USER
# Then log out and back in, or:
newgrp docker

Configuration

Section titled “Configuration”

Environment Variables

Section titled “Environment Variables”

You can customize the agent behavior with environment variables:

Edit the service file: ```bash sudo systemctl edit unboundbytes-agent ``` 
Add environment variables:
```ini
[Service]
Environment=RUST_LOG=debug
Environment=UB_ORCHESTRATOR_URL=https://custom.endpoint.com
```


Then restart:
```bash
sudo systemctl restart unboundbytes-agent
```
 ```bash RUST_LOG=debug unboundbytes-agent ```

Common Configuration Options

Section titled “Common Configuration Options”
VariableDescriptionDefault
RUST_LOGLog level (debug, info, warn, error)info
UB_ORCHESTRATOR_URLOverride orchestrator endpointhttps://orchestrator.unboundbytes.com
DOCKER_HOSTDocker socket path/var/run/docker.sock

Updating the Agent

Section titled “Updating the Agent”

The agent checks for updates automatically and applies them in the background. You don’t need to do anything.

To manually check for updates:

Terminal window
# The agent will check on startup
sudo systemctl restart unboundbytes-agent


# Watch the logs
sudo journalctl -u unboundbytes-agent -f

Troubleshooting

Section titled “Troubleshooting”

Agent Won’t Start

Section titled “Agent Won’t Start”
Terminal window
# Check logs for errors
sudo journalctl -u unboundbytes-agent -n 50


# Common issues:
# - Docker not running: sudo systemctl start docker
# - Agent already running: sudo systemctl status unboundbytes-agent
# - Port in use: sudo lsof -i :8080

Docker Permission Denied

Section titled “Docker Permission Denied”
Terminal window
# Add user to docker group
sudo usermod -aG docker $USER


# Apply new group membership
newgrp docker


# Verify
docker ps

Agent Can’t Connect to Orchestrator

Section titled “Agent Can’t Connect to Orchestrator”
Terminal window
# Check network connectivity
curl -v https://orchestrator.unboundbytes.com/health


# Check firewall
sudo ufw status
# Should allow outbound HTTPS (port 443)


# Check logs
sudo journalctl -u unboundbytes-agent -f

Device Won’t Pair

Section titled “Device Won’t Pair”
  1. Make sure the pairing code hasn’t expired (codes last 15 minutes)
  2. Restart the agent to get a new code:
    Terminal window
    sudo systemctl restart unboundbytes-agent
    sudo journalctl -u unboundbytes-agent -n 5
  3. Try pairing again in the portal

Uninstalling

Section titled “Uninstalling”

If you need to remove the agent:

Terminal window
# Stop the service
sudo systemctl stop unboundbytes-agent


# Remove the service
sudo systemctl disable unboundbytes-agent
sudo rm /etc/systemd/system/unboundbytes-agent.service
sudo systemctl daemon-reload


# Remove the binary
sudo rm /usr/local/bin/unboundbytes-agent

Next Steps

Section titled “Next Steps”

Once the agent is installed and paired:

  1. Deploy your first app - Deploy in 5 minutes
  2. Browse the app catalog - See what’s available
  3. Configure backups - Set up automatic backups