Configuration reference

CLI configuration

The Arctic CLI stores connection details in a configuration file.

File location

Default: ~/.config/arctic/config.yaml

Override with the --config flag or ARCTIC_CONFIG environment variable.

Configuration format

Groups peers by cluster with shared credentials and global preferences:

current_cluster: 01HABCDEF456...

clusters:
  01HABCDEF456...:
    cluster_id: 01HABCDEF456...
    customer_id: cust_xyz789...
    client_id: cl_01HXYZ...
    client_secret: sec_abc123...
    peers:
      - url: http://192.168.1.10:8080
        peer_id: 01HXYZABC123...
        name: agent-a
      - url: http://192.168.1.20:8080
        peer_id: 01HXYZDEF789...
        name: agent-b
    default_peer: 01HXYZABC123...
    name: Production

preferences:
  cache_ttl: 3600      # Cache TTL in seconds (default: 3600)
  auto_failover: false # Reserved for future use

Cluster object

Peer object

Preferences

Global CLI preferences that apply to all commands:

Preference details:

• output_format: Sets the default output format for all commands. Can be overridden with --output flag.
• color: Controls whether CLI output uses ANSI colors. Automatically disabled when NO_COLOR environment variable is set.
• timeout: Default HTTP request timeout for API calls. Can be overridden with --timeout flag.
• cache_ttl: Time-to-live for the completion cache in seconds. Cache is considered stale after this duration.
• auto_failover: Reserved for future peer failover feature. Currently not implemented.

Managing configuration

View current context:

arctic config current

Switch context:

arctic config use-cluster Production

List all contexts:

arctic config list

View full config:

arctic config view

Security considerations

The config file contains credentials. Protect it:

chmod 600 ~/.config/arctic/config.yaml

Consider using environment variables for CI/CD:

export ARCTIC_URL="http://agent:8080"
export ARCTIC_TOKEN="eyJ..."
arctic peers list

Compose configuration

The compose configuration file defines the desired state of an Arctic cluster in YAML format. This section documents the complete schema, field definitions, and validation rules.

File format

Configuration files use YAML format with schema version v1. The file can be named anything, but cluster.yaml is the convention.

Configuration schema

Root structure

Peer configuration

Notes:

• Peers cannot be deleted via compose. Removing a peer from the configuration file will not remove it from the cluster. Use arctic peers delete to remove peers.
• Peer names are used as references in service configurations.

Service configuration

Notes:

• A service must have either interface (with enabled: true) or routes defined.
• source_peer and target_peer must be different peers.

Interface configuration

Notes:

• If ipv4 is omitted, the address is assigned via DHCP.
• IPv4 cannot be 0.0.0.0/0 (broadcast address).
• IPv4 addresses must be unique per source peer across services.

QoS configuration

Notes:

• QoS is recommended for KCP transport to prevent bandwidth saturation.

Route configuration

Notes:

• At least one of source_cidr or dest_cidr must be specified.
• Cannot have both source_cidr and dest_cidr set to 0.0.0.0/0.
• Priorities must be unique within a service.
• Routes cannot conflict with another service on the same source peer (same source and dest CIDRs).

Validation rules

Errors

Errors must be fixed before the configuration can be applied.

Warnings

Warnings are advisory and do not prevent configuration from being applied. Use --strict to treat warnings as errors.

Canonical key ordering

The arctic compose fmt command reorders keys to a canonical order for consistency:

Root level: version, license, peers, services

Peer: name, address

Service: name, source_peer, target_peer, transport_type, fully_transparent, interface, qos, routes

Interface: enabled, ipv4

QoS: bandwidth_limit_mbps

Route: source_cidr, dest_cidr, priority

Examples

Minimal configuration

version: v1

peers:
  - name: peer-1
    address: 192.168.1.10:8080
  - name: peer-2
    address: 192.168.1.20:8080

services:
  - name: tunnel-1-to-2
    source_peer: peer-1
    target_peer: peer-2
    transport_type: tcp
    routes:
      - dest_cidr: 10.0.0.0/8
        priority: 100

Full configuration

version: v1
license: ./license.jwt

peers:
  - name: datacenter-west
    address: 10.0.1.10:8080
  - name: datacenter-east
    address: 10.0.2.10:8080

services:
  # West to East tunnel
  - name: west-to-east
    source_peer: datacenter-west
    target_peer: datacenter-east
    transport_type: tcp
    fully_transparent: true
    interface:
      enabled: true
      ipv4: 10.100.0.1/24
    qos:
      bandwidth_limit_mbps: 100
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.2.0/24
        priority: 100
      - source_cidr: 192.168.0.0/16
        dest_cidr: 172.16.0.0/12
        priority: 200

  # East to West tunnel (bidirectional)
  - name: east-to-west
    source_peer: datacenter-east
    target_peer: datacenter-west
    transport_type: tcp
    fully_transparent: true
    interface:
      enabled: true
      ipv4: 10.100.0.2/24
    qos:
      bandwidth_limit_mbps: 100
    routes:
      - source_cidr: 0.0.0.0/0
        dest_cidr: 10.0.1.0/24
        priority: 100

KCP transport with QoS

version: v1

peers:
  - name: site-a
    address: 192.168.1.10:8080
  - name: site-b
    address: 192.168.2.10:8080

services:
  - name: kcp-tunnel
    source_peer: site-a
    target_peer: site-b
    transport_type: kcp
    qos:
      bandwidth_limit_mbps: 50  # Recommended for KCP
    routes:
      - dest_cidr: 10.20.0.0/16
        priority: 100