Skip to main content

Install

The terminal CLI — install this first​

Get the CLI (recommended first install)

Every node serves the terminal CLI with a sha256-pinned installer — the fastest way onto the framework:

curl -fsSL https://zeqstate.com/install.sh | sh   # any node works as the origin
zeq tutorial   # guided: account → machine → first compute → verify

Full install notes + the complete command reference: /cli/.

The CLI is the gateway: zeq signup mints your identity + machine + API key from the terminal, and zeq sdk prints a quickstart wired to your key for every language below.

Language clients​

What ships today (no package manager involved — by design):

# Python — single file, stdlib only. Fetched from any node, never pip-installed.
curl -fsSO https://zeqapi.com/cli/zeq.py        # pin: /cli/zeq.py.sha256

# Every other language — raw HTTP. fetch()/net/http/URLSession against the same routes.
curl -s https://zeqapi.com/api/zeq/pulse

Planned, not yet published: the TypeScript/JavaScript package (@zeq-os/sdk) exists in-repo (app/packages/sdk/) but is private — there is no npm install @zeq-os/sdk yet (publishing is pending the self-hosted package-registry decision). To use it today, build it from the repo; otherwise plain fetch() has full parity — see SDKs → JavaScript.

That's the client only. You do not need to run the hosted compute layer. You need it to call the compute layer.

Getting an API key​

You have three options:

  1. Terminal CLI (fastest) — zeq signup "<phrase>" mints your ZID + machine + API key in one command; zeq keys mint <name> issues more. See /cli/.
  2. Hosted — sign up at zeq.dev, get a key, and you're computing in under 160 Zeqonds.
  3. Self-hosted — clone the repo, run the Docker stack, issue yourself a key locally. See Operate → Self-hosting for the full recipe.

Either way, the SDK call site is identical.

Environment​

Set the key in your shell environment:

export ZEQ_API_KEY="zeq_live_..."
export ZEQ_API_URL="https://zeqapi.com"   # default, change when self-hosting

(A client API key in your shell env is fine. Framework-side secrets are different — they live in the ZSC vault, never in a .env file; see ZSC bootstrap if you're self-hosting.)

Or pass it to the constructor (in-repo TS client):

import { ZeqClient } from "@zeq-os/sdk";

const zeq = new ZeqClient({
  apiKey: process.env.ZEQ_API_KEY,
  baseUrl: process.env.ZEQ_API_URL,
});

Verify the install​

Fastest check, any setup: zeq pulse (CLI) or curl -s https://zeqapi.com/api/zeq/pulse. With the in-repo TS client:

import { pulse } from "@zeq-os/sdk";

const p = pulse();
console.log(p);
// {
//   zeqond:    2292305743,   // floor(unix / 0.777000777)
//   phase:     0.412,
//   f_hz:      1.287,
//   T_s:       0.777,
//   R_t:       0.999917,   // R(t) = S(t) [1 + alpha sin(2 pi f t)]
// }

If f_hz: 1.287 and T_s: 0.777, the SDK is connected to a real Zeq clock — if either number differs, stop, the install is broken. If you're calling the hosted API as well, zeq.health() returns the server version and its authoritative Zeqond.

Next​

Run your first computation → Hello, Zeq.