CLI

axil capacity

Check if your machine and deployment can carry a target req/s with axil capacity: calibration or a real route, the Plan card, checks, readiness scan, CI JSON.

8 min readUpdated DocumentationEdit this page
On this page9

axil capacity (alias axil cap) answers one question: can this setup carry the target in axil.scaling.json? It measures real throughput, does the scaling arithmetic with your numbers, checks the host and the configuration, and scans src/ for state that breaks once you run more than one process.

Terminal
❯axil capacity --init # write a starter axil.scaling.json
❯axil capacity # calibrate one worker here, then plan
❯axil capacity --url http://localhost:3000/api/users --server-workers 8
❯axil capacity --json > capacity.json # CI: exit code 1 when the target cannot be met

The engine is @axiljs/scale; see Scaling for serve() and the programmatic API.

The honest numbers

No Node.js framework, and no framework in any language, serves millions of requests per second from one process or one machine. One @axiljs/core worker does roughly 15k to 25k req/s on a hello-world route, and real routes with database calls do less. Large targets are reached with more cores (vertical: one worker per core) and more machines (horizontal: instances behind a load balancer).

The planner's model is deliberately simple and printed in every report:

Output
TXT
instance rps  = rps per worker × min(workers, cpus) × 0.85   (cluster efficiency; ×1 for a single worker)
required rps  = target.rps × (1 + headroom)
instances     = ceil(required rps / instance rps)
instance mem  = workers × memoryPerWorkerMb + connections × 48 KB

For example, 1,500,000 req/s with 30% headroom on 8-CPU instances at 17k req/s per worker:

Output
TXT
1,500,000 × 1.3 ÷ (17,000 × 8 × 0.85) ≈ 17 instances of 8 CPU

Treat the result as a plan to confirm with a load test against a real deployment, not a guarantee.

Options

OptionDefaultDescription
--initWrite a starter axil.scaling.json and exit
--forceWith --init, overwrite an existing file (otherwise it fails with exit code 1)
--url <url>Measure your own running route instead of a hello-world calibration
--server-workers <n>1How many workers the server behind --url runs; total req/s is divided by it
--duration <s>5Measurement length in seconds
--connections <n>128Concurrent keep-alive connections
--jsonPrint the full report as JSON; exit code 1 when the verdict is fail

Step 1: describe the target

Terminal
❯axil capacity --init

writes:

JSON
JSON
1{
2  "target": { "rps": 10000, "concurrentConnections": 20000, "p99Ms": 100 },
3  "vertical": { "workers": "auto", "maxConnectionsPerWorker": 10000, "memoryPerWorkerMb": 512 },
4  "horizontal": { "instances": { "min": 2, "max": 6 }, "instanceSize": { "cpus": 4, "memoryGb": 8 } },
5  "headroom": 0.3
6}

Set target.rps and horizontal.instanceSize to your numbers. Every field and default is listed in Configuration. Without the file, axil capacity still runs on defaults and says so.

Step 2: measure

Without --url, it starts a hello-world server on @axiljs/core (the project's copy, else the one next to the CLI) in a single process and load-tests it from the other cores with a worker-thread load generator. That is a framework ceiling: your real routes are slower.

With --url, it load-tests your running server instead. Start it the way you run it in production, then tell the CLI how many workers it uses:

Terminal
❯npm run build && AXIL_WORKERS=4 npm start # in another terminal
❯axil capacity --url http://localhost:3000/api/users/1 --server-workers 4

Warnings tell you when a measurement is not trustworthy:

  • no --server-workers given: it assumes the server runs 1 worker;
  • failed requests (non-2xx or network errors), with their percentage;
  • a localhost URL: the load generator and the server share the CPU, so the server alone would do somewhat more;
  • fewer than 3 cores: the generator competes with the calibration server.

What the report shows

  1. This machine: CPU cores and model, memory (free), container CPU quota when limited, open-file limit, Node.js version.
  2. Calibrating one worker or Measuring your route: req/s and p50 / p99 latency.
  3. Plan card, marked fits, fits, with warnings or short:
    • Per worker: the measured req/s;
    • Per instance: workers on the instance size and the resulting req/s;
    • Deployment: req/s at instances.min and instances.max;
    • Target: target + headroom = required req/s.
  4. Checks, most severe first:
    • instance count: how many instances the target needs against instances.max, with the fix when it does not fit (raise max, or the CPU size needed per instance);
    • the autoscaler gap when min serves less than peak;
    • connections per worker against maxConnectionsPerWorker;
    • memory per instance against instanceSize.memoryGb (85% usable);
    • p99 at full load against target.p99Ms;
    • host checks: oversubscribed workers, workers: 'auto' inside a CPU-limited container, memory on this machine, the open-file limit (ulimit -n), and a note on Windows hosts;
    • a reminder when the plan rests on a hello-world calibration instead of your route.
  5. Multi-process readiness: when the config runs more than one worker or instance, a scan of src/ for in-memory state that splits across processes, with file and line:
Found in src/LevelWhy it breaks
rateLimit(warningCounts per process: the real limit becomes limit × workers × instances
new Scheduler(failureEvery cron job fires once per worker per instance
new Queue(warningIn-memory jobs live and die with the process that enqueued them
getGlobalEventBus( / new EventBus(warningSubscribers on other workers never see the event
new WSServer(warningBroadcasts reach only clients on the same worker
new CloudCache(warningInvalidations do not reach other workers
SQLite (better-sqlite3, type: 'sqlite')failureA local file: instances cannot share it

Each finding comes with its fix (a shared store, one scheduler process, a broker, PostgreSQL / MySQL).

Example output

An illustrative run of the starter file on an 8-core machine:

Output
TXT
  ┌  axil capacity  Can this setup carry the target?
  │
  ◇  Loaded axil.scaling.json
  │
  ◆  This machine
  CPU         8 cores · <cpu model>
  Memory      16.0 GB (9.4 GB free)
  Open files  unknown on this OS
  Node.js     v24.x
  │
  ◆  Calibrating one worker
  ◇  1 worker (@axiljs/core 0.3.6): 18k req/s  p50 6 ms · p99 14 ms
  │
  │  ╭ Plan ──────────────────────────────────────── fits ╮
  │  │ Per worker    18k req/s                            │
  │  │ Per instance  4 workers on 4 CPU / 8 GB → ~61k req/s│
  │  │ Deployment    2–6 instances → ~122k–367k req/s     │
  │  │ Target        10k req/s + 30% headroom = 13k req/s │
  │  ╰────────────────────────────────────────────────────╯
  │
  ◆  Checks
  ●  Based on a hello-world calibration (@axiljs/core 0.3.6)
  ◇  Target 10k req/s fits: 1 of max 6 instances needed
  ◇  20k connections → 834 per worker at 6 instances (limit 10k)
  ◇  Instance memory ~2.2 GB of 8 GB
  ◇  p99 14 ms at full load (target 100 ms)
  │
  ◆  Multi-process readiness
  ◇  No in-memory state that splits across workers/instances found in src/
  │
  ◆  This setup can carry the target in 9.4s
  │
  └

When the target does not fit, the flow ends with This setup cannot carry the target yet and a recommendation such as Recommended: workers 'auto', instances { min: 6, max: 17 } of 8 CPU, and the exit code is 1.

Exit codes and CI

SituationExit code
Fits, or fits with warnings0
Any failing check, or a failing readiness finding (new Scheduler(, SQLite)1
--json and the planner verdict is fail1
Measurement failed (server unreachable, 0 req/s)1
--init when the file exists, without --force1

--json prints one object with system, scaling (resolved config), measurement, measured (raw load-test result), report (verdict, model, instance, deployment, required, recommended, findings) and readiness. In a pipeline:

Terminal
❯npm run build
AXIL_WORKERS=4 NODE_ENV=production npm start &
❯axil capacity --url http://127.0.0.1:3000/api/users/1 --server-workers 4 --duration 10 --json > capacity.json

The step fails when the configured deployment can no longer carry the target, for example after a change made a hot route slower.

From plan to deployment

axil deploy reads the same axil.scaling.json: replicas from instances.min, a HorizontalPodAutoscaler up to instances.max, pod resources from instanceSize, AXIL_WORKERS pinned to the pod's CPUs and a termination grace period that covers the drain. See axil deploy.

The high-scale-api template is set up for this workflow: it ships an axil.scaling.json, runs serve() on every core and has tests that validate the scaling file.

Next steps

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY