Release Notes

Release notes for the self-hosted Arctic agent and CLI. Newest releases are listed first.

1.4.1

A maintenance release that closes the last gap in the 1.4.0 "no host dependencies" promise and fixes several cluster and access issues. In 1.4.0 the agent programmed the kernel directly, but the QoS traffic shaper still shelled out to tc, ip, and modprobe. On a host hardened per the 1.4.0 guidance (those packages removed), enabling QoS would fail to start. 1.4.1 moves the QoS data plane onto the kernel directly as well, so the guarantee now holds whether or not QoS is enabled.

This release also makes the KCP tunnel transport selectable and extends bandwidth shaping to it, and fixes break-glass recovery, peer revocation, and a handful of startup and multi-homed networking issues.

Highlights

• No host dependencies, now including QoS: The traffic shaper now programs the kernel directly, so enabling QoS no longer requires iproute2 or the tc binary on the host. The running agent executes no external commands on its data path.
• KCP transport works again: A service set to transport_type: kcp once more uses the KCP (UDP-based) tunnel. A 1.4.0 regression silently ran these services over TCP instead.
• QoS shaping reaches KCP: Per-service bandwidth_limit_mbps now applies to KCP tunnels in both directions, not just TCP.
• Recovery and revocation fixes: The break-glass recovery token can now reliably mint credentials to restore access to a locked cluster, peer revocations converge reliably across the cluster, and a revoked peer can no longer silently rejoin.

Upgrading to 1.4.1

1.4.1 is a drop-in upgrade from 1.4.0. There are no configuration, schema, or API changes.

• You can remove iproute2 and tc now: If you kept these installed on a QoS-enabled host because of the 1.4.0 gap, they are no longer needed. QoS still requires the kernel itself to provide the shaping features (the sch_cake, sch_ingress, act_mirred, and ifb modules, built in or loadable); 1.4.1 removes the userland binary requirement, not the kernel-feature requirement.
• Clearing a peer revocation is now per node: Re-add the peer on each node that revoked it rather than relying on gossip to carry the reactivation.

Networking and data plane

• QoS over the kernel directly: The traffic shaper is now programmed directly through the kernel instead of shelling out to tc, ip, and modprobe. A genuinely missing kernel feature surfaces as a clear error and disables QoS gracefully.
• Fixed: KCP transport silently fell back to TCP: KCP worked before 1.4.0, but consolidating the data plane into the single agent introduced a regression where a transport_type: kcp service would quietly fall back to TCP. In the cases where KCP did activate, timing issues could break the link. KCP services are now wired through to the KCP tunnel reliably.
• Bandwidth shaping for KCP: bandwidth_limit_mbps now caps KCP traffic in both directions.
• Fixed: bandwidth_limit_mbps: 0 is now truly unlimited: With QoS enabled, a link with no explicit limit was silently capped at a 10 Gbit default instead of running unshaped. Such links are now left unshaped end to end. To turn QoS off for a whole node, disable qos_enabled on the peer.
• Fixed: startup under boot ordering: An agent that started before its default route existed (for example before a DHCP lease came up) could bind outbound links to the wrong interface, or leave QoS disabled, until a restart. Interface and QoS state are now resolved on every reconcile pass and self-heal within the resync window without a restart.
• Fixed: KCP on multi-homed and shared-subnet hosts: On a host whose service interface shared a subnet with the physical NIC, KCP tunnels could stall because replies went out from the wrong source address. The KCP listener now replies from the exact address each request arrived on, so KCP works on any multi-homed host.

Cluster and access fixes

• Recovery token can mint credentials: Presenting the break-glass recovery token previously unreliable when creating a credential, is now fixed.
• Peer revocations converge across the cluster: A peer revoked on one node could stay active on nodes that knew it only through gossip. Revocations now ride normal gossip and converge everywhere.
• Revoked peers cannot silently rejoin: A revoked peer that kept running could previously out-version its revocation and reactivate itself through gossip. Only an explicit operator re-add can now bring a revoked peer back.

1.4.0

This is a large release. The headline change is that Arctic is now a single agent binary: the separate proxy and tunnel services that earlier versions ran alongside the agent are now built into it. There is one binary to install and manage instead of three, and a target host no longer needs any extra packages or dependencies. It just has to be a machine running a Linux Kernel.

Beyond the consolidation, 1.4.0 brings tighter controls for locked-down deployments, safer cluster operations, and broader QoS tuning, plus fixes for a TCP throughput regression and a tunnel stall on poor links. The highlights and full details are below.

Highlights

• One binary: Arctic ships as a single agent. The binary dropped from roughly 71 MB to roughly 23 MB.
• No host dependencies: The agent runs no external commands and programs the kernel directly, so a host only needs to be a Linux machine (no NetworkManager, iproute2, nftables, or tc to install). This matters most for locked-down and embedded deployments.
• Locked-down operations: Expose a single node to operators and keep the rest reachable only from inside the cluster, with a break-glass recovery token to regain access if a cluster gets locked. See Recovery and Hardening.
• Safer cluster changes: A cluster-wide apply lock prevents two operators applying at once, and version pinning keeps every peer on a compatible agent version.
• QoS for tough links: Fixed or default RTT, optional latency probing, and a memory cap for multi-gigabit links.

Upgrading to 1.4.0

1.4.0 changes how the agent is packaged and run. The upgrade is automatic, but review these notes first. See the Upgrades guide for the full procedure.

• Legacy services are removed automatically: On upgrade the installer stops, disables, and removes the old TProxy and IP-tunnel system units, their binaries, and their config files. The cleanup is safe to run more than once.
• No host packages required: Because the agent talks to the kernel directly, you no longer need NetworkManager, iproute2, nftables, or tc installed. They can be removed if nothing else on the host uses them.
• Peer address is deprecated: Use the new endpoints list instead. The single address field still works but produces a lint warning.
• Database migrations run on first start: The agent migrates its database automatically the first time 1.4.0 starts. Take a backup beforehand as usual. See Backup and restore.

Single agent binary

The data planes now run inside the agent process. The agent supervises them and restarts them if they fail. The firewall is now programmed directly through the kernel rather than by shelling out to command-line tools, so the agent does not depend on NetworkManager, iproute2, nftables, or tc being installed. On older kernels that lack nf_tables, the agent falls back to a legacy backend automatically (IPv4 only) and logs a warning so you can see it.

Locked-down access and recovery

• Internal API mode: Set a peer's api_access to internal so it refuses operator-facing API calls while still talking to other peers. This lets you expose a single node to operators and keep the rest reachable only from inside the cluster.
• Manage internal peers through the server: An operator does not lose control of an internal-only peer: a reachable, full-access peer transparently forwards operator requests to it over the cluster, so one front-door node can manage the whole cluster.
• Break-glass recovery token: At boot the agent writes a read-only recovery token to disk (mode 0600). Presenting it grants admin access on any request that carries it (until the next agent restart), even to a node in internal API mode, and every use is logged. Use it to regain control when a cluster is locked or an operator loses access. See Recovery.
• Hardening guide: New documentation walks through locking down a Linux host that runs the agent. See Hardening.

Cluster management

• Version pinning: A compose requires.agent constraint forces every peer to satisfy a version range before an apply proceeds, so you avoid running mismatched features across a cluster. See Compose.
• Dedicated server role: Mark a peer as a server and name it in a server block as the node that is reliably reachable across the cluster. This also lays the groundwork for future server-side features.
• Fallback endpoints: A peer can list several endpoints (for example https://west.internal and 10.0.1.10:8080) that peers and operators try in order, so reachability can follow the client's network and internal DNS.
• Cluster apply lock: arctic compose apply now takes a cluster-wide lock so two operators cannot apply at once. A blocked apply reports the conflict, and a crashed operator's lock expires on its own. arctic compose diff warns when a lock is held but does not block.

Networking

• VLAN tagging: Set vlan_id on an interface to put a service's tunnel interface on an 802.1Q VLAN.
• Stable interface MAC addresses: Tunnel interfaces now default to a deterministic MAC derived from the cluster, peer, and service names, so the MAC stays the same across reboots without you pinning it by hand. You can still set an explicit MAC.
• Fixed: tunnel stall on poor links: On a very unreliable link, dropped handshakes and health checks could leave the IP-tunnel receiver wedged over time, eventually stalling all tunnel traffic until the service was restarted. The receiver now recovers on its own and no longer blocks.

See Configuration reference for the full set of interface options.

Performance and QoS

• Faster TCP transfer: A regression that forced TCP data through a slow user-space copy was fixed.
• Non-disruptive service updates: Changing one service now rebuilds only that service; the other services on the host keep running and their active connections survive.
• Default RTT: Set default_rtt_ms to seed the traffic shaper's round-trip time instead of relying on the built-in default.
• Disable RTT probing: Set disable_auto_rtt to fix the shaper to the configured RTT and stop probing, for volatile links where measured RTT swings unpredictably.
• QoS memory cap: Set memlimit_cap_mb to bound the memory the shaper uses. This matters on multi-gigabit links, where a 10 Gbit path can otherwise size its queues into several gigabytes of kernel memory and exhaust a memory-constrained host such as an embedded or field device.

See Configuration reference for the QoS options.

CLI and tooling

• compose diff: A new command shows the difference between your config file and the live cluster before you apply.
• Local state and history: The CLI keeps a working-directory cache in .arctic/ that tracks what was last applied (for accurate diffs), serializes concurrent runs on the same machine with a local lock, and keeps timestamped backups of previous applied states. Use arctic state unlock to clear a stuck lock.
• Stronger validation: Compose validation catches more mistakes up front (endpoint and MAC formatting, VLAN ranges, server-block and routing rules), and the same checks run in the Configuration Builder so the web tool and the CLI agree.
• Machine-readable output: Add --json to commands for stable output you can script against.
• MCP server: arctic mcp starts a local server that lets AI assistants such as Claude and ChatGPT drive the CLI against your cluster. Read operations are available by default; making changes requires opting in with --allow-write. See the CLI reference.
• Rebuilt configuration builder: The Configuration Builder was rebuilt. It now validates with the same code the CLI uses, compiled to run in the browser, so the web tool and the CLI won't drift.