Quickstart

By the end of this quickstart you will have two hosts accelerating TCP between them. You define a small cluster (two peers and one service) in a YAML compose file, apply it with a single command, and route your traffic through it.

Create a Cluster Configuration

Create a file called cluster.yaml with your cluster configuration:

version: v1

license: license.json    # Path to your license file

peers:                   # Define all hosts in the cluster
  - name: node-a
    endpoints:
      - 192.168.1.10:8080
  - name: node-b
    endpoints:
      - 192.168.1.20:8080

services:
  - name: tunnel-a-to-b
    source_peer: node-a  # Where traffic enters
    target_peer: node-b  # Where traffic exits
    transport_type: tcp
    interface:
      enabled: true      # Create a MACVLAN interface for routing

Each peer can list more than one entry under endpoints (for example a LAN address and a public address); the cluster tries them in order. The older single address field still parses but is deprecated, so prefer endpoints.

Place your license.json file in the same directory as cluster.yaml.

Apply the Configuration

Apply the configuration to create your cluster:

arctic compose apply ./cluster.yaml

export ARCTIC_CLIENT_ID=cli_xxxxxxxxxxxxxxxxxxxxxx
export ARCTIC_CLIENT_SECRET=sec_xxxxxxxxxxxxxxxxxxxxxxx

Verify the Setup

After compose apply returns, confirm the cluster came up as expected:

# List peers and their connectivity
arctic peers list

# List services
arctic services list

# Get full service details (including the assigned interface IP)
arctic services get <service-id>

The <service-id> is a ULID shown in the output of arctic services list. peers list and services list give you a summary table; services get returns the full detail for one service.

Updating Your Cluster

cluster.yaml is the source of truth. To change the cluster, edit the file and re-run the same apply flow. Validate first, preview the diff, then apply:

# Check the configuration is well-formed
arctic compose validate ./cluster.yaml

# Preview what would change against the live cluster
arctic compose diff ./cluster.yaml

# Apply the changes
arctic compose apply ./cluster.yaml

The CLI compares your file against the live cluster and updates only what changed, so re-applying an unchanged file is a no-op.

Service Configuration Options

The quickstart example uses the default MACVLAN interface mode. Here are additional configuration options.

Static IP Assignment

Assign a static IPv4 address to the service interface:

services:
  - name: tunnel-a-to-b
    source_peer: node-a
    target_peer: node-b
    transport_type: tcp
    interface:
      enabled: true
      ipv4: 192.168.3.32/24  # Static IPv4 with subnet

Policy-Based Routing

Route specific subnets through the tunnel instead of using a MACVLAN interface. Use this when MACVLAN is unavailable (for example, some cloud environments):

services:
  - name: tunnel-a-to-b
    source_peer: node-a
    target_peer: node-b
    transport_type: tcp
    routes:
      - dest_cidr: 172.31.8.0/24
        priority: 100
      - dest_cidr: 172.31.0.0/16
        priority: 200

Priority breaks ties between routes of equal specificity, and a lower priority value wins. In the example above, traffic to 172.31.8.0/24 matches the first route (priority 100) before the broader 172.31.0.0/16 route (priority 200). Specificity is checked before priority: a MACVLAN interface match beats a source+dest CIDR match, which beats a source-only CIDR, which beats a dest-only CIDR.

Troubleshooting

Agent Not Starting

Check logs for errors:

journalctl -u arctic -f

Common causes: port 8080 already in use, or the agent not running as root.

Compose Apply Fails

• Verify all agents are running: curl http://<ip>:8080/livez
• Check the license file exists and is valid (the agent re-verifies the license on every startup)
• Ensure network connectivity between agents

Handshake Fails

• Both agents must use the same license
• Agents must reach each other on port 8080
• Check for firewall rules blocking ports 8080/TCP, 51840/UDP, and 61000/TCP

Next Steps

You now have a working Arctic cluster with encrypted tunnels between your hosts. Explore the Compose guide for more advanced cluster management options.