Connecting Nodes

This guide covers how to connect your servers (nodes) to Shardlyn so you can deploy applications on them.

Overview

Shardlyn manages applications on your infrastructure. You bring the servers, and Shardlyn handles orchestration, monitoring, and deployments. There are two ways to add nodes:

Method	Best For
Cloud Provisioning	New servers — Shardlyn creates and configures them automatically
Manual Registration	Existing servers — install the agent on servers you already have

Cloud Provisioning

The easiest way to add nodes. Shardlyn provisions servers on your cloud account automatically.

Supported providers: AWS, GCP, Hetzner Cloud, Oracle Cloud (OCI)

1. Add your cloud credentials in Settings > Credentials
2. Navigate to Nodes > Provision Server
3. Select provider, region, and instance size
4. Click Apply

Shardlyn uses Terraform to create the server and automatically installs the agent. See the Provisioning Guide for detailed setup per provider.

Manual Node Registration

For servers you already manage:

Via Dashboard

1. Navigate to the Nodes page
2. Click Add Node
3. Copy the installation command
4. SSH into your server and run the command

Via API

Generate a registration token:

curl -X POST https://api.shardlyn.com/v1/nodes/register-token \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Install the agent on your server:

curl -fsSL https://get.shardlyn.com/install.sh | sh -s -- --token YOUR_TOKEN

Advanced examples:

# Enable terminal + SFTP access and expose host files
curl -fsSL https://get.shardlyn.com/install.sh | sudo bash -s -- \
  --token YOUR_TOKEN \
  --enable-terminal \
  --enable-host-files \
  --host-files-allow-paths /home,/srv,/var/log,/etc

# Work around unstable IPv6 on the node's network path
curl -fsSL https://get.shardlyn.com/install.sh | sudo bash -s -- \
  --token YOUR_TOKEN \
  --prefer-ipv4

# Register with an API token scoped to nodes.create
curl -fsSL https://get.shardlyn.com/install.sh | sudo bash -s -- \
  --token YOUR_API_TOKEN \
  --organization-id YOUR_ORG_ID

Agent Requirements

The Shardlyn agent requires:

• Linux (x86_64 or ARM64)
• Docker installed and running
• Outbound HTTPS access to api.shardlyn.com
• No inbound ports required (agent initiates all connections)

Optional install flags:

• --enable-terminal: configures SSH + reverse tunnel for web terminal and SFTP
• --enable-host-files: exposes allowed host paths to the file browser/SFTP
• --host-files-allow-paths /home,/srv,/var/log: narrows the host filesystem exposed by the agent
• --prefer-ipv4: forces IPv4 for control plane traffic on nodes with broken/intermittent IPv6
• --organization-id: required when the token is an API token instead of a one-time registration token

Node Lifecycle

Once connected, nodes go through these states:

State	Description
Pending	Registration token created, waiting for agent
Healthy	Agent connected and reporting heartbeats
Unhealthy	Agent reported a degraded or unhealthy condition
Offline	No heartbeat received for 5+ minutes, or the node is disconnected

Monitoring Your Nodes

The Nodes page in the dashboard shows:

• Real-time status and health
• CPU, memory, and disk usage
• Running instances per node
• Heartbeat history

Firewall Configuration

The agent only needs outbound HTTPS access. No inbound firewall rules are required for the agent itself.

For your applications, open the ports defined in your workload configurations (e.g., 25565/tcp for Minecraft).

Troubleshooting

Agent Not Connecting

1. Verify the server has outbound HTTPS access
2. Check that the registration token hasn't expired (production defaults to short-lived tokens)
3. Ensure Docker is installed and running: docker info
4. Check agent logs: journalctl -u shardlyn-agent

Node Shows Unhealthy

1. Verify the server is online and has network connectivity
2. Check agent status: systemctl status shardlyn-agent
3. Review agent logs for errors: journalctl -u shardlyn-agent -f
4. If IPv6 is unstable on that host, reinstall or update the agent with --prefer-ipv4

Next Steps

• Cloud Provisioning — Automate server creation across AWS, GCP, Hetzner, and OCI
• Workloads — Define container templates to deploy on your nodes
• Security — Configure MFA, SSH certificates, and API tokens
• Observability — Monitor node health, metrics, and dashboards