Edge nodes — run jobs on your own machine

An edge node is a computer you own running a Spike worker. It pulls jobs from Spikefrost, executes them locally with your own Claude Code or Codex seat, and streams the result back into the conversation that asked for it.

Reach for one when the work has to happen on your hardware: a private repository, an internal network the cloud can't route to, a machine that already holds the credentials and tooling. As a side effect, the model usage bills to your own coding-agent account rather than your Spikefrost balance.

Fast path — a fresh Linux box or EC2 instance

One command as root turns a clean machine into a ready node:

curl -fsSL https://edge.spikefrost.com/sf/ec2-bootstrap.sh | sudo bash

Works over SSH on any systemd distribution, and works equally as cloud-init user-data pasted at instance launch — the instance comes up with the node already running.

It installs and configures, in order:

1. git — a hard requirement of every snapshot task. Amazon Linux ships without it.
2. The codex CLI (via npm) and the claude CLI (Anthropic's native installer, per-user). A claude failure is non-fatal: codex-only nodes work fine.
3. The Spikefrost CLI and edge runner, which bring their own Node runtime.
4. loginctl enable-linger — see below. This is the step people miss.
5. The systemd user service, registered and started, surviving logout and reboot.

It finishes by printing the node's connection string and a next-steps banner.

The linger trap

Worth stating on its own, because it is the single most common support issue with Linux nodes:

Without loginctl enable-linger, systemd terminates your user service when the last SSH session closes. The symptom is distinctive: the node works perfectly all day while you are connected, and is offline the next morning.

The bootstrap enables it. If you set a machine up by hand, or inherited one that keeps disappearing, check it:

loginctl show-user $USER --property=Linger

Linger=yes is what you need. Anything else and the node will not survive your logout.

Two things the bootstrap deliberately does not do

Both are per-customer and interactive by design — the machine runs your own AI seat, so no script can do them for you.

1. Sign in to the AI CLI, as the user the service runs as:

codex login --device-auth

claude setup-token

Either is enough; the node uses whichever provider an agent asks for.

2. Attach the node to a cluster — the console step described next.

Sizing

Existing machine — step by step

For a Mac, or a Linux box you already run and would rather configure yourself. Install the CLI first if you haven't:

curl -fsSL https://edge.spikefrost.com/sf/install.sh | sh

Then print the node's connection string:

sf edge pair

Run the worker in the foreground to watch the startup checks:

sf edge run --verbose

Once it looks right, install it as a background service. This survives a restart, starts on login, and keeps the machine awake so dispatched jobs aren't missed:

sf edge service start

status, stop and restart do what you'd expect, and start installs the service first if it isn't installed yet. On Linux, remember linger.

Attaching the node to a cluster

This applies to both paths, and the direction matters — it is the opposite of what most people assume:

The machine prints its connection string. The console receives it. There is no code issued by the console that you type on the machine.

1. In the console open Connectors and add a Spike edge node connector, or open the one you already have. The connector is the cluster — one connector holds several machines, and agents address the cluster, so you can add hardware later without touching agent code.
2. Choose Add node and paste the connection string the machine printed.

The string looks like spike-edge-node://connect?token=…, and you can re-print it at any time:

sf edge pair

Treat it as a credential. It carries the node's pairing token, so don't paste it into a ticket, a chat channel, or anywhere you wouldn't paste a password. Rotate it whenever you need to:

sf edge regenerate-token

Verify it is working

Three commands, in the order worth running them:

sf edge status

sf edge logs --lines 20

You are looking for Gateway accepted edge-node session in the log. And on Linux:

loginctl show-user $USER --property=Linger

One log line deserves recognition rather than debugging:

Connected, but this node is NOT paired to a cluster yet — its pairing token is not registered.

That means the runner reached Spikefrost but its connection string was never added to a cluster. Finish the console step; the node binds itself on the next retry.

Give the cluster its environment

Variables set on the cluster are handed to every execution on every node in it — the right home for an internal API base or a key the jobs need locally:

sf edge env list

sf edge env set API_BASE https://internal.example.com

Using it from an agent

The machine becomes an agent's tool. Declare it on the agent class:

override tools = {
  workstation: this.edgeComputerTool({
    alias: 'my_mac_mini',        // the connector — i.e. the cluster
    provider: 'claude',          // or 'codex'
    repos: [                     // mounted beside the app, always pulled
      { provider: 'github', fullName: 'acme/api' },
    ],
  }),
};

Five behaviours decide whether your design works. They are not edge cases:

The turn ends at dispatch. The tool returns "started", not a result. The machine then works alone for minutes and the answer arrives later as a new message in the same conversation. Never await it, poll it, or re-dispatch — holding the turn open produces duplicate replies.

Dual mount, always fresh. The app's own code is always checked out, every declared repository beside it, and all of them pulled before the CLI starts. A tree with uncommitted work from a previous turn is not pulled — the agent is told so in its preamble rather than losing the work.

Two push verbs. sf app push publishes app code; git push publishes a mounted repository. The machine publishes neither on its own, and its workspace persists — so ending a turn mid-refactor is normal and safe.

The session is the conversation. Follow-up instructions resume the same CLI session on the machine, so the agent can refer back to earlier work. A different conversation gets a fresh session.

One job per computer and app. A second command for the same app while one is running is rejected with a typed error. Relay that to the user in plain language rather than retrying. A different app on the same computer runs concurrently.

And the constraint that shapes the prompt: no progress, no steering, no cancel mid-run. Describe the outcome you want, not the keystrokes, and expect nothing back until it finishes.

What the machine can reach

The node's access is yours to bound, and the defaults are conservative:

Beyond that: a node only ever executes jobs dispatched to its own cluster, the pairing token is rotatable, and the credentials the work uses are the ones already on your machine — Spikefrost never sees your Claude or Codex login.

Configuration reference

Every flag has an environment-variable equivalent, which is usually the better choice for a background service.

sf edge help prints the complete list, including the upgrade-source overrides.

Keeping it current

sf edge version

sf edge upgrade

The runner checks for upgrades while idle by default. Pin the version on a machine where you don't want that, with --no-auto-upgrade or SPIKE_EDGE_AUTO_UPGRADE=0. Add --force to reinstall at the same version.

Troubleshooting

Next

• Tools and data — the rest of what an agent can be granted.
• The sf CLI — installing and signing in.
• Download — get the CLI and the desktop app.