> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mesh Agent

> Connect your on-premise infrastructure to ShiftLabs securely

Mesh Agent connects your on-premise infrastructure to ShiftLabs through an encrypted WireGuard-based mesh network. No inbound ports or complex firewall rules required.

## Prerequisites

* Linux server (Ubuntu 22.04 or 24.04 recommended)
* Root or sudo access
* Outbound internet access (no inbound ports required)
* Subnets you want to expose (e.g., `10.150.50.0/24`)

## How to Create an Agent

<Steps>
  <Step title="Open Mesh Agent Page">
    Go to **Mesh Networking → Mesh Agent** and click **Create Agent**.
  </Step>

  <Step title="Enter Agent Details">
    * **Name**: Descriptive name (e.g., `production-dc-istanbul`)
    * **Location**: Physical location (e.g., `Istanbul Data Center`)
    * **Customer Subnets**: Network ranges to expose (e.g., `10.150.50.0/24`)
  </Step>

  <Step title="Save">
    Click **Create**. You'll receive installation instructions with your authentication key.
  </Step>
</Steps>

## How to Install the Agent

After creating the agent, run the installation script on your server:

```bash theme={null}
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up \
  --login-server=https://headscale.shiftlabs.dev \
  --authkey=YOUR_AUTH_KEY \
  --advertise-routes=10.150.50.0/24
```

<Note>
  The actual script with your authentication key is displayed after agent creation.
</Note>

## How to Approve Routes

<Steps>
  <Step title="Open Agent Details">
    Go to **Mesh Networking → Mesh Agent** and click on your agent.
  </Step>

  <Step title="Go to Routes Tab">
    Click the **Routes** tab.
  </Step>

  <Step title="Enable Routes">
    Toggle the switch to enable each pending route.
  </Step>
</Steps>

Your infrastructure is now connected to ShiftLabs.

## How to Add New Subnets

<Steps>
  <Step title="Update Agent Configuration">
    On your agent's detail page, click **Edit Subnets** and add the new subnet.
  </Step>

  <Step title="Update Server">
    On your server, re-run with all subnets:

    ```bash theme={null}
    sudo tailscale up --advertise-routes=10.150.50.0/24,172.16.0.0/24
    ```
  </Step>

  <Step title="Approve Route">
    Approve the new route in the **Routes** tab.
  </Step>
</Steps>

## How to Set Up High Availability

For redundancy, install the agent on multiple servers using the same authentication key.

<Steps>
  <Step title="Create One Agent">
    Create a single agent in ShiftLabs.
  </Step>

  <Step title="Install on Multiple Servers">
    Run the installation script on 2+ servers using the same key.
  </Step>

  <Step title="Verify">
    All nodes appear under the same agent in the **Nodes** tab.
  </Step>
</Steps>

<Tip>
  If one node goes offline, traffic automatically routes through available nodes.
</Tip>

## How to Rotate Authentication Keys

<Steps>
  <Step title="Open Agent">
    Go to your agent's detail page.
  </Step>

  <Step title="Rotate">
    Click **Rotate Key** and confirm.
  </Step>
</Steps>

<Info>
  Existing connections are not affected. Only new node registrations use the new key.
</Info>

## How to Delete an Agent or Node

**Delete a node:**

1. Go to agent detail → **Nodes** tab
2. Click delete icon on the node
3. The node disconnects immediately

**Delete an agent:**

1. Go to agent detail page
2. Click **Delete** and confirm

<Warning>
  Deleting an agent disconnects all nodes immediately and cannot be undone.
</Warning>

## Network Requirements

Mesh Agent requires only **outbound** connectivity:

| Protocol | Port  | Purpose             |
| -------- | ----- | ------------------- |
| UDP      | 41641 | WireGuard tunnel    |
| HTTPS    | 443   | Coordination server |

<Info>
  No inbound ports need to be opened on your firewall.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent shows as Inactive">
    1. Check server has internet connectivity
    2. Verify Tailscale service is running:
       ```bash theme={null}
       sudo systemctl status tailscaled
       ```
    3. Restart if needed:
       ```bash theme={null}
       sudo systemctl restart tailscaled
       ```
  </Accordion>

  <Accordion title="Routes not working">
    1. Verify routes are enabled (not "Pending") in Routes tab
    2. Enable IP forwarding:
       ```bash theme={null}
       sudo sysctl net.ipv4.ip_forward=1
       ```
    3. Check advertised routes:
       ```bash theme={null}
       tailscale status
       ```
  </Accordion>

  <Accordion title="Authentication failed">
    1. Verify you copied the complete installation script
    2. Check if authentication key expired
    3. Generate new key with **Rotate Key** and reinstall
  </Accordion>

  <Accordion title="Connection drops frequently">
    1. Check network stability on agent server
    2. Verify firewall isn't blocking UDP port 41641
    3. Check for IP conflicts in your network
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How many agents can I create?">
    No limit. Create as many as needed for different locations.
  </Accordion>

  <Accordion title="Can I use the same subnets across different agents?">
    Yes. ShiftLabs handles IP translation automatically to prevent conflicts.
  </Accordion>

  <Accordion title="What happens if my agent goes offline?">
    It shows as "Inactive". Operations targeting that infrastructure will fail until reconnected. The agent reconnects automatically when network is available.
  </Accordion>

  <Accordion title="Do I need a static IP?">
    No. Works with dynamic IPs and behind NAT.
  </Accordion>

  <Accordion title="How do I migrate an agent to a new server?">
    1. Install on new server using the same authentication key
    2. Verify new node appears in Nodes tab
    3. Delete the old node
  </Accordion>
</AccordionGroup>