Private Beta: Getting Started

Welcome to the ZeroLock private beta. This page is everything you need to connect your agents to a hosted ZeroLock gateway. It is pre-release software: expect rough edges, and tell us when you find them.

What you receive

Your contact at ZeroLock sends you, through a one-time secret link (never by plain email or chat):

Your environment is a private namespace. Shards, audit events, approvals, live subscriptions and usage count only against your key, so you cannot see or disturb other beta users, and they cannot see you.

Keep the key secret like a password: put it in an environment variable or secret store, never in source control, front-end code or logs. If it leaks, tell us and we revoke it within seconds and issue a new one.

Install

TypeScript (Node 18 or newer)

npm install @zlock/sdk-ts@beta
npm install ws          # needed on Node 18 and 20 for live (WebSocket) features; Node 22+ has it built in

Python (3.10 or newer)

pip install --pre zerolock-sdk

Both packages are pre-release (beta) builds. Ask for them explicitly with @beta and --pre: that keeps working unchanged once a stable release exists, and it keeps your installs from jumping to a newer pre-release by accident. The TypeScript SDK pulls in its one dependency, @zlock/schema, by itself; the Python SDK depends only on httpx and websockets.

Check what you got:

npm ls @zlock/sdk-ts @zlock/schema
pip show zerolock-sdk

If you were sent files instead of using the registries, install them directly: npm install ./zlock-schema-<version>.tgz ./zlock-sdk-ts-<version>.tgz and pip install ./zerolock_sdk-<version>-py3-none-any.whl.

Your first calls

Set the key once, in your shell or secret manager:

export ZEROLOCK_GATEWAY="https://dxxxxxxxx.cloudfront.net"
export ZEROLOCK_API_KEY="zl_..."

Check the gateway is up (no key needed):

curl "$ZEROLOCK_GATEWAY/ready"        # {"status":"ready"}

TypeScript

import { ZeroLockClient } from '@zlock/sdk-ts';
 
const client = new ZeroLockClient({
  gateway: process.env.ZEROLOCK_GATEWAY!,
  apiKey: process.env.ZEROLOCK_API_KEY!,
  agentId: 'planner-1',                 // see "Agent identity" below
  runId: 'run-001',                     // optional: groups this run's events in traces
});
 
await client.createShard('plan', { type: 'decision', initialValue: { step: 0 } });
 
const shard = await client.getShard<{ step: number }>('plan');
await client.commitShard('plan', { step: shard.value.step + 1 }, shard.version);

Python

import asyncio, os
from zerolock_sdk import ZeroLockClient, CreateShardOptions
 
async def main():
    async with ZeroLockClient(
        gateway=os.environ["ZEROLOCK_GATEWAY"],
        api_key=os.environ["ZEROLOCK_API_KEY"],
        agent_id="planner-1",
        run_id="run-001",
    ) as client:
        await client.create_shard("plan", CreateShardOptions(type="decision", initial_value={"step": 0}))
        shard = await client.get_shard("plan")
        await client.commit_shard("plan", {"step": shard.value["step"] + 1}, shard.version)
 
asyncio.run(main())

If two agents commit against the same version, one gets a 409 conflict. That is the product working: re-read the shard, decide again, and retry. See the TypeScript SDK and Python SDK guides for conflict handling, task claiming, caching and live subscriptions.

Live updates (WebSocket)

Subscriptions and cache invalidation use a WebSocket. On Node 20, pass the ws package:

import WebSocket from 'ws';
import { ZeroLockWSClient } from '@zlock/sdk-ts';
 
const ws = new ZeroLockWSClient({
  wsUrl: `${process.env.ZEROLOCK_GATEWAY!.replace('https', 'wss')}/ws`,
  apiKey: process.env.ZEROLOCK_API_KEY!,
  agentId: 'planner-1',
  webSocket: WebSocket,
});
await ws.connect();

On Node 22 and later you can omit webSocket. Browsers cannot send the key on a WebSocket, so run agents server-side.

Try the full example: a Gemini support desk

Once your first calls work, the fastest way to see everything ZeroLock does is the Support Desk walkthrough. It is a complete, working example that runs against your beta gateway with the packages you just installed (@zlock/sdk-ts and zerolock-sdk, nothing else):

• three Gemini agents claim tickets from one queue, so exactly one agent works each ticket;
• they draw from a shared refund budget, and version checks stop two agents spending the same money;
• every customer reply is held until a separate supervisor key approves it;
• a verifier then checks all of it against the gateway's state (PASS or FAIL).

It is written in both TypeScript and Python, step by step with the code and an explanation of each part, and the two languages can even work the same queue together. For it you need two keys on your environment: the normal worker key and a second supervisor key that can resolve approvals. Ask your contact for the second one.

Agent identity

Your key can be bound to one agent id (we tell you if it is). An agent id appears on every audit event, which is how you see who did what. If you run many agents, ask for one key per agent or per role, so a leaked key can be revoked without stopping everything else.

Limits during the beta

Your environment has quotas, set by us and visible on request:

Other fixed limits: request bodies and WebSocket messages up to 256 KiB, and a request rate limit per key. Going over returns a 413 (too large), 429 (slow down, honor the Retry-After header) or a quota error. Ask us if you need more.

What to expect

• Pre-release: the service can restart for updates (connections drop and the SDK reconnects), and data may be wiped between beta phases. We announce wipes beforehand. Do not store anything you cannot recreate.
• Not for production traffic or personal data. Use synthetic or non-sensitive data.
• Single region, single database (no cross-region failover yet).
• No SLA. We watch the service and fix problems quickly, but there is no uptime guarantee.
• Anything you send is stored in our database and in audit events for 7 days.

Getting help

Send us: the time of the problem (with timezone), your environment id, the agent id, the request path and the HTTP status. Never send the key itself. We can look up your requests by environment and time.

Common errors:

Next steps

1. Run the Support Desk example end to end.
2. Read the TypeScript SDK or Python SDK guide for conflict handling, task claiming, caching and live subscriptions.
3. Replace the example's tickets with your own work: any queue of tasks, shared number or irreversible action maps onto the same three patterns.
4. Tell us what broke or felt awkward. That is what the beta is for.