Agents

An agent is the process that runs steps. It dials out to Hyperspool, claims work matching the capabilities it advertises, runs it, and reports back. Most work never needs an agent of yours: Hyperspool starts managed environments on demand for the common capabilities. You run your own agents when those don’t fit, as Running your own agent describes.

Managed environments

When a step needs shell, polyglot, connector or build and none of your own agents is free to take it, Hyperspool starts an environment, runs the step there, and lets the environment go after about two idle minutes. There is nothing to install or register.

Capability	Environment
shell, polyglot, connector	A container with bash, coreutils, sed, grep, gawk, findutils, git, openssh, curl, go, node 22, python3 (the Python SDK imports as hyperspool), make and gcc. Up to 2 CPUs, 1 GiB of memory, a 2 GiB working directory and 1 GiB in /tmp.
build	An amd64 Ubuntu 24.04 VM with 16 cores, 32 GiB of memory, 200 GiB of disk and KVM, where steps run as runner with passwordless sudo. It serves one run, and takes a minute or two to start. On the Team and Business plans. Build VMs has the details.

What a step asks for decides which one it gets. A pipeline job with steps: needs shell; a script: job or a canvas code node needs polyglot; http and connector nodes need connector. A job’s requires: adds capabilities, so requires: [build] puts it on a build VM. agent: pins a job to one agent id, which means one of yours.

Limits to plan around

• The containers have no bun, deno, rust/cargo, jq or docker. Install them on a build VM with sudo apt-get or Nix (Build VMs shows how), or run your own agent.
• Containers and build VMs reach the public internet only. Private addresses (10/8, 172.16/12, 192.168/16 and the like), link-local and cloud metadata addresses are blocked.
• Outbound mail ports (25, 465 and 587) are blocked from every managed environment, so SMTP connections time out. To send mail, call your provider’s HTTPS API (Postmark, SES, Resend, Mailgun and the like) from an http or connector node, or send from an agent of your own.
• An environment lives an hour by default. A step that declares a longer timeout: gets an environment that lives long enough for it, up to four hours. The environment needs some of that time to start and to report, so the longest timeout: that fits is 3 hours 40 minutes. A longer step fits in no managed environment; run it on an agent of your own.
• Environments are kept apart per org, project and trust level, and a build VM serves the one run it was started for. Work from an untrusted event (a fork pull request, an outside contributor’s comment) always gets a fresh environment that serves that one step, and none of the project’s secrets.

A step that nothing can take shows as unroutable: none of your agents advertises what it needs, and no managed environment provides it. Usually that is a capability of your own naming (linux-arm64, gpu) with no agent running for it, or a build step on the Free plan.

Managed environments show in spool agent list while they run, beside your own agents, and drop off a day after they finish.

What your plan includes

Each plan bounds how many runs an organization has going at once, how much managed compute it uses, and how much of each run it keeps:

	Free	Team	Business	Enterprise
Runs at once	2	5	10	agreed
Runs at once, on your own agents only	20	200	500	agreed
Managed environments at once	2	5	10	agreed
Build VMs at once	none	1	2	agreed
vCPU-minutes per 30 days	600	6,000	20,000	agreed
Log stored per run	512 MiB	4 GiB	8 GiB	no limit
Finished runs kept for	14 days	90 days	365 days	agreed

The second row applies to an organization set to use only its own agents (ask support). A run started at the cap waits its turn rather than failing; Before a run starts explains what counts and how the queue works. What happens past the log limit is in Log size, and what is deleted when a run ages out is in Retention.

Managed compute

An environment counts the CPUs it can use, from the moment it is started until it exits: 2 for a container and 16 for a build VM. An hour in a container is 120 vCPU-minutes, so Free’s 600 is five container-hours, and an hour on a build VM is 960. The 30 days roll: usage older than that stops counting. Settings > Usage and spool org usage show where your organization stands.

When your organization is at a limit, no new environment is started for it and the step waits. spool run why <run> and the run page say which limit holds it:

• your plan has no build VMs: run your own agent that advertises build, or move to Team or Business;
• the allowance is used up: the step starts once older usage leaves the 30-day window, or run your own agent;
• as many environments are running as the plan allows: the step starts when one of them finishes.

Work already running is never stopped by a limit. Steps your own agents take, and environments you start with your own dispatcher, don’t count toward the managed compute limits.

When to run your own agent

Run one when you need:

• another platform: arm64, macOS, anything other than amd64 Linux;
• your private network, or a database or service that isn’t public;
• tools the container doesn’t carry and you’d rather not fetch with Nix on every build;
• special hardware (a GPU, a device), or a step longer than a managed environment can hold;
• build steps on the Free plan, or more managed compute than your plan includes;
• all of your org’s work on your own machines. An org can be set to use only its own agents; ask support. Its work then never runs on managed environments.

An idle agent of yours that can take a step gets it; a managed environment starts only for work none of yours can pick up. Running your own agent covers tokens, installing the agent and keeping its jobs apart from it.