Slotlock

Slotlock

Slotlock is a calendar for AI agents. It books vehicles, rooms, machines, people or anything else reservable, answers "when is this free?" from weekly availability rules, and lets PostgreSQL reject double bookings, however many writers race. Agents call it over MCP or A2A; your code calls it as a TypeScript library.

Why it is built for agents

• Resources own calendars, not users, and the tenant comes only from the authenticated caller.
• Intervals are half-open [start, end), so back-to-back bookings never collide.
• A PostgreSQL exclusion constraint decides overlaps; a conflict comes back as data, not an error.
• Writes are idempotent and take an expected revision.
• Free/busy says whether it is *certain*: a calendar not yet synced makes time unproven, not free.
• Tool names, schemas and errors work on Claude, OpenAI and every MCP host.

Install

npm install slotlock postgres

Node.js 22.12+, PostgreSQL 16 or newer with btree_gist (created for you if missing; CI runs 16, 17 and 18), and postgres ^3.4.5 as a peer dependency. TypeScript declarations are included.

Self-host with Docker

From a clone of this repository:

scripts/quickstart-env.sh > .env    # .env.example, its four secrets set to openssl rand -hex 32

docker compose up --build --detach docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/London

• Metrics count calls by protocol, operation and outcome (slotlock_calls_total, with their duration in slotlock_call_duration_seconds), confirmations, subscriptions, refusals, maintenance and webhook deliveries. No label names a tenant, key or client. createSlotlockMetrics builds them for a server of your own, from its hooks.
• The server runs as a role that owns nothing and cannot bypass row-level security; a one-off migrate service applies the schema as the owner.
• SLOTLOCK_AVAILABILITY sets the default bookable hours. A resource can have its own (slotlock hours set, or the dashboard); with neither, no slot is offered. SLOTLOCK_CONFIRM_WRITES=all (as .env.example sets it; the server's default is none) makes every write wait for a person.
• To serve beyond this machine, put a TLS proxy in front and set SLOTLOCK_PUBLIC_URL.
• The server limits requests per client address (before any key is looked up), per key, per tenant and for the whole server, and answers 429 rate_limited with Retry-After and the RateLimit fields. The application API counts an admin key's calls in its tenant's own app_read and app_write budgets, apart from the agents'; another key's are its own. A recurring create and every event update (a new title re-expands a recurring event's series too) takes its write token, then waits for a slot: one at a time per tenant (tenant_series_writes) and per server (series_writes); each server process counts its own. A freed slot rests for as long as the server was busy while the write before held it (at most a second), so with one slot, writes that each hold it under a second keep the server busy at most about half the time. It then goes to the waiting tenant with the fewest writes in flight and, among those, the one whose writes have kept the server busy least lately (halving every ten seconds), then to the first to ask. So a tenant sending one write at a time waits for the write running, its rest, and the other tenants with one write in flight whose writes kept the server less busy: many such tenants, new ones included, can each go ahead of it once. Tenants keeping more writes waiting never go ahead of it. Four more of a tenant's writes may wait and the rest get 429. When the server's 64 places are all taken, a write from a tenant with fewer writes in flight than the tenant with the most takes the place of that tenant's last write, which gets 503 server_busy; otherwise it gets 503 at once. An expansion runs on the server's main thread, so any request may also wait for the one running. A write that has waited two seconds gets 429 while its tenant's own write is still running, otherwise 503 server_busy. An application API maintenance run waits the same way for slots of its own: one per tenant, maintenance_runs per server. The health check is not counted. One tenant's requests hold at most tenant_transactions (2) of the server's 10 database connections at once and the rest wait their turn, so a tenant's writes waiting on its own locks leave the others to other tenants and key lookups; a server with one tenant can set tenant_transactions=10. A request whose transaction waits more than 5 seconds for a lock gets 503 server_busy. With more than one server, SLOTLOCK_SHARED_LIMITS=on shares the tenant budgets (tenant_*, app_*) through the database, so N servers allow a tenant its rate once, not N times; each server checks its own buckets first, and goes on with them alone if the database cannot be reached. SLOTLOCK_LIMITS changes the limits; behind a proxy, set SLOTLOCK_TRUSTED_PROXY_HEADER to the field it puts the client's address in (CF-Connecting-IP behind Cloudflare) before the server takes traffic, or every client shares the proxy's budget: the server logs a client_address_field_ignored warning when such a field arrives without the setting. Behind two proxies, such as Cloudflare and then kamal-proxy, name the first one's field: the server reads the last address of a list field such as X-Forwarded-For, which the second proxy writes as Cloudflare's. A client can send that field itself, so let nothing reach the server except through the proxy.
• The server also bounds what one tenant may store, whichever key, agent or application writes it: 10,000 holds, and 100,000 each of bookings, calendar events and coverage rows, counted as the store's tenantLimits count them, besides 10,000 resources. A write past one answers 409 hold_limit_reached, reservation_limit_reached, event_limit_reached or coverage_limit_reached; SLOTLOCK_LIMITS changes them (tenant_holds, tenant_reservations, tenant_events, tenant_coverage).

slotlock hours set '[{"rrule":"FREQ=WEEKLY;BYDAY=SA","startMinutes":600,"durationMinutes":240}]' --resource vehicle-42

slotlock hours clear --all # back to SLOTLOCK_AVAILABILITY

A rule is rrule, startMinutes and durationMinutes here and in SLOTLOCK_AVAILABILITY. The REST application API spells every field in snake_case, so there it is rrule, start_minutes and duration_minutes. slotlock --help lists every setting.

Booking rules

A resource can also say what a booking on it must satisfy:

slotlock rules set '{"minNoticeMinutes":120,"slotStepMinutes":30,"turnaroundMinutes":30,"enforceHours":true}' --resource vehicle-42

slotlock rules clear --resource vehicle-42

• Holds, reservations, moves and agents' events are checked when they are made, by the database's clock; a refusal names the rule (booking_rule_violated with rule in the store, booking_rule_min_notice, _max_advance, _slot_step, _outside_hours or _uncertain to an agent). Under requireCertain, a search (the store's and the tools') needs those syncs' coverage too, read within a day, of the slot and its turnaround, so it offers no slot they leave unproven.
• A series is judged on its first occurrence for notice and advance, and on every occurrence for step and hours. Imported calendar events are not checked: they happened elsewhere.
• Searches (slotlock_find_next_available, slotlock_find_available_slots, findNextAvailableFor) offer only slots the rules allow, so an offered slot is one the write accepts.
• Two bookings stay at least the earlier one's trailing buffer plus the later one's leading buffer apart: each occupies from its start less its leading buffer to its end plus its trailing one, and the exclusion constraint keeps those apart. Free/busy reports that time as busy.
• The REST application API sets them with PUT /v1/resources/{resource_id}/booking-rules, in snake_case; the store with setResourceBookingRules.
• Defaults: rules for every resource of the tenant (PUT /v1/booking-rules) and for every member of a pool (PUT /v1/pools/{pool}/booking-rules), read back with GET /v1/booking-rules; the store's setBookingRuleDefaults and getBookingRuleDefaults. A resource's rules as they apply (effective_booking_rules, effectiveBookingRules) are the tenant's defaults, overlaid by its pool's, overlaid by its own: a rule set at a narrower level wins. checkInMinutes is a resource's own only. The dashboard's resource page shows which rules a resource inherits, and from where.
• With no rule set anywhere, nothing changes: every rule is opt-in.
• A tenant has default rules for at most 1,000 pools (pool_rules_limit_reached, 409, for one more). Merged rules are read leniently: a pool's stepOffsetMinutes under a resource's shorter step applies modulo that step, and a field that is invalid on its own is ignored (and logged), never read as refusing every booking.

Without Docker

With Node.js 22.12+ and PostgreSQL 16 or newer, run each command as npx slotlock after npm install slotlock postgres, or from a clone, built once, as node dist/cli.js (a clone does not put slotlock on your PATH). Use two roles, as Compose does, so two URLs: serve connects as DATABASE_URL, a role that owns nothing and cannot bypass row-level security, and migrate connects as SLOTLOCK_MIGRATE_DATABASE_URL, the schema owner, and grants that role what it needs. serve refuses to start as a superuser or a BYPASSRLS role, which row-level security does not confine, and warns (serving_as_schema_owner) when its role owns the schema.

npm ci && npm run build

Once, as a superuser:

CREATE ROLE slotlock_app LOGIN PASSWORD ' ' NOSUPERUSER NOBYPASSRLS;

export SLOTLOCK_MIGRATE_DATABASE_URL='postgresql:// : @localhost:5432/slotlock' export DATABASE_URL='postgresql://slotlock_app: @localhost:5432/slotlock' export SLOTLOCK_AUTH_TOKEN="$(openssl rand -hex 32)" export SLOTLOCK_CONFIRMATION_SECRET="$(openssl rand -hex 32)" node dist/cli.js migrate node dist/cli.js resource add vehicle-42 --timezone Europe/London node dist/cli.js serve

The slotlock … commands in this README run the same way as node dist/cli.js … (with Compose, docker compose exec slotlock slotlock …).

API