Help › Guide
Using a server
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
A Reqlyn server keeps what you publish and runs it for others: through its run API, from the desktop's Catalog, as routes under /routes, as MCP tools, on a schedule, or through a private agent in another network. It keeps a record of every run, and watches each version's upstream APIs for change.
This page is for people who use a server. Installing one is in INSTALL_SERVER.md, step by step; running one, every setting included, in DEPLOYMENT.md.
Workspaces, roles and tokens
Everything on a server belongs to a workspace. A caller is a person signed in through the server's identity provider, or a service token for programs. Each has one role in a workspace, and the roles are a ladder:
| Role | May also |
|---|---|
| viewer | read what is published |
| operator | run and cancel |
| editor | save drafts; read drafts, their reviews and kept bodies |
| publisher | publish versions and activate them |
| administrator | keep secrets, bind environments, give roles, issue tokens, apply the deployment manifest |
A token or a person can also be limited to named operations and environments; what they do not reach is not there for them (it answers 404, as for a name nobody has). A limited caller is a viewer or an operator.
A workspace and its first token are made on the server's computer:
reqlyn-server workspace create "Network"
reqlyn-server token issue "Network" "ci" operator --environments lab
The token is printed once; only its hash is kept. A person's first role is given the same way, by the identity provider's identifier of the person: reqlyn-server member grant "Network" <subject> administrator. After that, administrators give roles from Settings > Members (or PUT /v1/members/{subject}), and issue tokens from Settings or POST /v1/tokens. A token issued so lasts 90 days unless expires_in_days (1 to 3,650) or never_expires: true says otherwise, and is refused after; the list gives each one's expires_at. A token reqlyn-server token issue makes on the server itself does not expire.
Linking the desktop
In Settings, under "Reqlyn server", give the server's address and a service token, and press Link. Or, on a server with an identity provider, press "Sign in with the browser": the browser goes to the provider and back, and you choose one of the workspaces you hold a role in. The title bar and the status bar then name the workspace, and Runs and Catalog appear on the rail.
The token is kept in this computer's secret store and is sent only over HTTPS, or to a server on this computer. Tests still run on this computer: every Run action says where it runs.
The command line
The reqlyn remote … commands use no data folder. The server and the token come from the environment, never from an argument:
REQLYN_SERVER=https://reqlyn.example
REQLYN_TOKEN=rqs_…
reqlyn remote list
Publishing
- In the operations editor, press "Publish…". The operation goes to the server as a draft, and the server's review replaces the editor:
- what would stop the publication;
- what changed since the latest version: inputs, output, steps, requests, limits, regression cases;
- whether a caller of the latest version is still served: inputs and output shape are checked, behavior never is and is always said to be not verified;
- the most requests a run can send;
- what each environment does not bind among the variables and credentials the requests name.
- "Publish version" makes the version, and the screen says its number. Versions are numbered by the server and never change.
Nothing is sent to any API by publishing. If someone else saved the server's draft since you last sent it, the desktop stops before sending and says so; it replaces their draft only when you ask by name. A draft made elsewhere, in a browser or on another computer, is listed in the desktop's Operations sidebar under ON THE SERVER; choosing it says what opening it saves here, and "Open here" saves it on this computer under the server's id, so that publishing from here goes to the same draft. A draft made from recordings also shows the calls described and an example of each.
Environments and secrets
An environment holds the variables a version's requests name and the credentials they are sent with. Every save is a new revision; a run keeps the revision it was given. Administrators set them through the API:
curl -X PUT -H "Authorization: Bearer $REQLYN_TOKEN" -H "Content-Type: application/json" \
https://reqlyn.example/v1/secrets/inventory-token -d '{"value": "…"}'
curl -X PUT -H "Authorization: Bearer $REQLYN_TOKEN" -H "Content-Type: application/json" \
https://reqlyn.example/v1/environments/lab -d '{
"content": {
"variables": [{ "name": "inventory", "value": "https://inventory.example" }],
"credentials": [{
"name": "inventory", "kind": "bearer", "secret": "inventory-token",
"destinations": ["https://inventory.example"]
}]
}
}'
- A secret is sealed under the installation key; no answer ever holds its value.
- A credential binding names its kind (
bearer,basicwithusername,digestwithusername, whose secret is the password that answers the server's Digest challenge and is never sent,ntlmwithusername, a Windows account (DOMAIN\useroruser@domain) whose secret is its password, answered to the server's NTLM challenge on one connection and never sent,oauth1withconsumer_key,method(HMAC-SHA1,HMAC-SHA256,RSA-SHA256orPLAINTEXT) and, as it has them,token,realmandtoken_secret(another secret's name, the token's secret), whose secret is the consumer secret or, for RSA-SHA256, its private key in PEM, each request signed with them as RFC 5849 says,hawkwithid, whose secret is the Hawk key that MACs each request and its body,kerberoswithusername(user@REALM) andkdc(a host,host:portortcp://host:port), whose secret is the password: a ticket toHTTP/and the address's host is asked of the KDC for each request and sent as Negotiate, the password never sent; the KDC'stcp://host:porthas to be among the binding's destinations and the server's allowed destinations (tcp://dc.corp.example.com:88), and a KDC on an internal network needs that network allowed too (REQLYN_PRIVATE_NETWORKS),headerwithheader,oauth_clientwithclient_id,token_urlandscope,aws_sigv4withaccess_key_id,regionandservice, whose secret is the secret access key and signs each request, AWS Signature Version 4, without ever being sent, orjwt_assertionwithissuerandexchange, andaudience,subject,scope,token_urlandtoken_pathas it needs, whose secret is an RSA private key in PEM that signs a JWT (RS256), sent as itself (exchange: bearer), exchanged attoken_urlwith the jwt-bearer grant (jwt_bearer, a Google service account), or posted there as a bearer token for the token attoken_pathin the answer (bearer_post, a GitHub App's installation token), oroauth_loginwithclient_id,authorize_url,token_url,scopeand, for a confidential client,client_secret(a secret's id), whose secret keeps the refresh token an administrator's "Sign in" on the environment's page obtains: the browser goes to the provider and comes back to the server's/v1/oauth/callback, which needsREQLYN_WEB_URL; runs on the server use it, a private agent's do not; withper_person: trueit names no secret, and each person signs it in with their own account from their Account page, the runs they ask for sent as them and anyone else's refused, orloginwithusernameandlogin_url, whose secret is the password: the server posts them to the login address inbody({{username}}and{{password}}where they go;{"username":…,"password":…}when not given), as Basic too withbasic: true(then the body may be left out), takes the token attoken_pathin the answer (access_tokenwhen not given;$for an answer that is the token itself), holds it in memory and sends it asAuthorization: Bearer, or inheaderafterprefix(X-Auth-Token;CookieafterAPIC-cookie=), logging in again once an API answers 401; after three failed logins in a row it tries no more until the environment is saved again; the login address has to be among its destinations; runs on the server use it, a private agent's do not yet), the secret that holds its value or a place in HashiCorp Vault (vault: { mount, path, key }), and the origins it may be sent to, one to twenty. It is sent nowhere else, whatever the request says (CREDENTIAL_NOT_FOR_DESTINATION). - Saving again sends
based_on_revision, the revision you read, so that a change made meanwhile is not written over. reqlyn remote environmentslists each environment and its latest revision.
Above every binding, the server's operator decides where runs may send at all (REQLYN_ALLOWED_DESTINATIONS), and an address of the server's own network is refused unless allowed.
Activating a version
A version runs only in an environment it is activated in:
reqlyn remote activate <operation id> 3 lab
Activating checks that the environment binds every variable and credential the version's requests name, and replays the version's regression cases with nothing sent; it sends nothing to any API. From the desktop, the publication screen activates too.
Where the deployment manifest names an environment under approval:, activating there waits for a second person: a publisher or administrator, signed in as a person, other than whoever asked. They approve or refuse it in Settings > Approvals, or with reqlyn remote approvals, approve <request> and refuse <request>. A request left a week expires.
A version's state:
- active;
- retired: still runs where it is activated, and is activated nowhere new;
- disabled: no run of it is accepted.
reqlyn remote version <operation id> <version> retired.
Running
reqlyn remote run <operation id> 3 --environment lab --input '{"deviceId": 4831}'
It waits for the run and prints its output, ending as a local run does (0, 1, 2 or 3). Also:
--key <text>: asked again with the same key and input within a day, it gives the same run and makes no other.--max-age <seconds>: a result that young is given in place of a new run, where the manifest lets that version be cached.--no-wait: prints the run's id and stops.reqlyn remote status <run>,events <run>andcancel <run>follow it.
The run API is POST /v1/operations/{id}/versions/{version}/runs with {"environment": "lab", "input": {…}}, and ?wait=<seconds> (up to 30) to wait for it. A file input is an upload's id: reqlyn remote upload <file>.
Cancelling a run under way stops its request in flight, marks that step uncertain, and does not undo what it did. A run under way when its server stops ends interrupted, and is never sent again.
The Catalog
Catalog, on the rail once a server is linked, lists what the workspace has published, each at its latest version with its inputs and output and who published it. Search finds an operation by part of its name, id or publisher; the choice under it narrows to active, retired or disabled versions.
An entry's tabs:
- Overview: the version's contract, its state, and a run form: choose an environment, fill the inputs (checked against the contract before anything is sent), and run it on the server. A version a step of which names a read shows "Read first, write nothing".
- Schedules: see below.
- Changes, from the second version on: what changed from an earlier version, whether its callers are still served, and where each output field comes from, step by step.
- Drift: see below.
- OpenAPI and MCP: the generated OpenAPI description, how to connect an MCP client, the routes that reach the operation with their calls over the last 24 hours, and how each version is hosted.
Beside the entry's name, each published version can be chosen, and the whole entry follows it.
Runs
Runs, on the rail, lists the workspace's runs newest first, narrowed by operation, environment or state. A run shows its version, environment, binding revision, caller, times and each step on one honest time scale, with its requests (method, address, status, size, time; never a header or a body). A credential read from a vault is named with its version, never its value. Two runs of one operation can be compared field by field, leaving out places or matching list items by a key.
A run keeps no body unless its operation, or its hosting, says it keeps bodies and the server keeps an evidence folder; then each body is sealed, masked for the secrets the run used, and readable by editors at /v1/runs/{id}/evidence until it expires.
Load
A load run runs a published version again and again: as many virtual callers as asked, starting one after another over the ramp, for as long as asked, and at most so many runs a minute among them if a rate is given. Each of its runs is an ordinary run sent by the server, so every request waits its turn under the workspace's shared rate limits however many callers there are; they are kept with the load run and left out of the runs list. It reports its runs, how many succeeded and failed, runs a minute, each run's latency at the 50th, 90th, 95th and 99th percentiles and the most, failures by code, and the same for each step.
- What: a version with a step that may write is loaded only with
--writes, as each of its runs writes again. - Where: only in an environment an administrator lets take load,
reqlyn remote load-policy <environment> on [--callers <n>] [--seconds <n>], within its ceiling (50 callers for 10 minutes unless set), one load run at a time there, and not in one a private agent carries. - Who: operators and above start and stop one; any member reads it. Starting, stopping and the policy are in the audit trail.
- From the command line:
reqlyn remote load <operation id> <version> --environment <name> --callers <n> --seconds <n> [--ramp <seconds>] [--per-minute <n>] [--input <json>]waits for its end and prints what came of it, ending with 1 when a run failed;--no-waitprints its id,reqlyn remote load-status <id>reads it andreqlyn remote load-stop <id>stops it after the runs under way.
Forks of a draft
Anyone who may edit drafts can fork one: POST /v1/drafts/{id}/forks makes a draft of its own, <id>-fork-<six hex>, with the draft's content at its revision then. A fork is read and saved as any draft is, by anyone who may edit drafts, and POST /v1/forks/{fork}/proposal offers it back. GET /v1/forks/{fork}/parts says how it differs from the draft as it is now, part by part: the inputs, the output, each step by its name and each request by its id, each added, changed or removed, with both sides. Anyone who may edit drafts but whoever proposed it takes it: POST /v1/forks/{fork}/take with the draft's revision the parts were read against and the parts chosen (["request:device"]), or none for all of them. A step the fork adds goes in after the step before it in the fork. The draft is saved only when what it becomes holds together, as any save is checked; a take against a revision the draft has moved past is refused (409), so read the parts again. POST /v1/forks/{fork}/decline declines it. GET /v1/drafts/{id}/forks lists a draft's forks and where each stands, and GET /v1/forks every fork of the workspace; forking, proposing, taking and declining are in the audit trail.
On the desktop, an operation the server holds has "Fork on the server" under its actions: the fork is made and offered to open here, as any draft of the server's is. A fork open here says so, "A fork of <draft>, not proposed yet.", with "Propose to <draft>", which sends the fork as it is saved here and proposes it. Proposals waiting to be taken are listed under PROPOSALS in the Operations sidebar; choosing one shows its parts with a box ticked beside each, both sides of each, and "Take chosen", "Take all" and "Decline". A copy of the draft on this computer is as it was until it is opened from the server again. A request taken from a server's draft is sent back under the draft's id, so its parts compare as the same request.
In the web client, a draft's Forks view has "Fork this draft", which opens the fork to edit as any draft, and lists the draft's forks and where each stands. On an open fork the view has "Propose to <draft>"; on a proposed one, its parts, each ticked or not, with "Take chosen", "Take all" and "Decline"; whoever proposed it is told that someone else takes it.
Drafts from a Git remote
A workspace's drafts can be taken from a branch of a Git repository, so that publishing follows a merged pull request. An administrator names the remote: PUT /v1/git-source with {"url": "https://git.example/team/ops.git", "branch": "main", "path": "reqlyn", "token_secret": "git-token"}. Only an https:// address is fetched, with no user or password in it; the token is a secret of the workspace (token_secret) or a place in the server's vault (token_vault, as a credential binding names one), sent to the remote as a header and never written. GET /v1/git-source says what is set and the commit last taken; DELETE removes it.
POST /v1/git-source/fetch (a member who may edit) fetches the branch now and takes the folder at path. It holds what a folder workspace writes, operations/<id>.yaml with requests/<id>.yaml and each operation's <id>.cases.yaml, and Arazzo documents (<name>.arazzo.yaml, the draft <name>), each compiled with the descriptions beside it and its <name>.cases.yaml. Each becomes the draft of that id, saved as the member who asked. A draft edited on the server since it was taken, or made on the server, is left as it is and listed under kept with why; one the same as the branch is counted unchanged; a file that is not a draft is listed under problems. Publishing a taken draft is as for any draft, and activating it still waits for a second person where the workspace asks for one. Setting, removing and each take are in the audit trail.
The server runs the installed git (the server image has it) with fixed arguments and an environment of its own: no configuration of the server's user, no prompt, the https protocol only, no redirect followed. The remote is fetched as a run's request is sent: only when its origin is one the operator allows (REQLYN_ALLOWED_DESTINATIONS) and every address its host resolves to is one the server may reach (REQLYN_PRIVATE_NETWORKS); git is held to the addresses checked. A link committed to the branch is written as a plain file and never followed. As with a credential binding's origins, an administrator decides where the token goes; the remote and each change of it are in the audit trail. It clones the branch alone into a folder of its own, removed after. A remote signed by an authority of your own is trusted with REQLYN_GIT_CA_FILE (DEPLOYMENT.md).
So that a merge is taken without anyone asking, give the forge a webhook. POST /v1/git-source/webhook-secret (an administrator) makes its secret, replacing one made before, and answers with the webhook's path, /v1/git-source/webhook/<workspace id>, and the secret, shown this once. In GitHub or Gitea, add a webhook for pushes to the server's address and that path, content type JSON, with the secret; in GitLab, a push hook with the secret as its token. A call signed with it (GitHub's X-Hub-Signature-256, Gitea's X-Gitea-Signature, GitLab's X-Gitlab-Token) is answered 202 at once and the remote is taken in the background, as git-webhook in the audit trail, a take that fails there as git.source.failed with why; any other call is refused (401), whatever the workspace. GitHub's ping when the hook is made is answered 204 and takes nothing.
Mocks for an environment
An administrator puts a mock in an environment from an OpenAPI description: PUT /v1/environments/{environment}/mocks/{name} with {"description": "<the description's text>", "stateful": true}. It answers at /v1/environments/{environment}/mocks/{name}/answer/<path>, any method, as a mock on the desktop does: each call its description's example or realistic data generated from its schema, the same for the same call; when stateful, a POST of a JSON object is kept and read, listed, changed and deleted at its id after. Only a caller with a token or a session of the workspace is answered. Its records are kept in the server's database, so every server process answers alike; it keeps at most 10,000, and POST …/mocks/{name}/reset (a member who may run) forgets them. GET /v1/environments/{environment}/mocks lists an environment's mocks; DELETE …/mocks/{name} (an administrator) removes one. Putting, resetting and removing are in the audit trail.
A run on the server reaches its environment's mock without leaving the server: a request whose address is mock://<name>/<path> (written so in the request, or through a variable the environment binds, such as a base address of mock://inventory/api) is answered by the server itself from that environment's mock of that name, with no destination, rate limit or credential, since nothing is sent. In an environment without that mock the run fails and says so. A private agent cannot answer one: a mock is answered on the server.
Schedules
A version that only reads can be run on a schedule, from its Catalog entry's Schedules tab or the API: an interval in minutes, or a cron expression read against UTC; an environment; fixed inputs; and the service token it runs as. A due time the server missed by more than about a minute is recorded as skipped, never run late. A refused one is recorded with its reason. A schedule can be paused.
Routes and the deployment manifest
What a workspace hosts beyond its versions is one file, applied whole by an administrator:
reqlyn: deployment/1
routes:
- method: GET
path: /devices/{deviceId}/health
operation: device-health
version: 3
environment: lab
versions:
- operation: device-health
version: 3
environment: lab
limits: { max_requests: 50, max_seconds: 30 }
reads_only: true
cache: { max_age_seconds: 300 }
approval: [prod]
reqlyn remote apply deployment.yaml
reqlyn remote apply deployment.yaml --yes
The first prints the plan, each entry added (+), changed (~) or removed (-); --yes applies it. One wrong entry and nothing is applied.
A route answers under the server's /routes, here GET /routes/devices/4831/health, to a caller allowed to run that version there. Its inputs come from the path and query, or a JSON body for POST. Within 30 seconds it answers the output (200), the run's reason (502), or where to read the run (504). A GET route needs a version that only reads. A caller that sends Cache-Control: max-age=60 may be given a cached result, with an Age header.
A route's run is made inside its request. While the server's database cannot be reached, routes called with a service token are still answered from what the server last read, and their runs written once the database is back.
The manifest also holds hosting choices per version and environment (versions:), which private agent takes which environment (agents:), the applications that use each version (consumers:), shared rate limits per upstream origin (rate_limits:), and group-to-role maps for SCIM and LDAP. DEPLOYMENT.md describes every field.
MCP tools
The server offers published versions to Model Context Protocol clients at POST /v1/mcp, with a service token (or, where the operator set it up, an access token from the identity provider) as the bearer. A tool is one version, <operation>_v<version>, taking an environment and the operation's input; a call makes an ordinary run. A client is offered the versions it may run whose steps only read. A version that writes is offered only once an administrator allows it (reqlyn remote tool <id> <version> allow), and takes an idempotency_key. No tool takes an address.
A coding agent authors drafts at the same endpoint. To a caller that may edit drafts (an editor or above; a token limited to some operations or environments is at most an operator and is offered none), it also offers the assistant's tools over drafts: list_drafts, read_draft (secrets masked), add_draft with its first step and output, add_step, add_input, add_output and change_output. Each change is saved to its draft at once and is in the audit trail (mcp.authored); a request holding a secret is refused; nothing is published or run by them. Give an agent a service token of its own with the editor role: reqlyn-server token issue <workspace> <name> editor.
The web client
The question mark at the right of the title bar opens this documentation, served by the server at /help/, at the part that says how the screen you are on is used; the question mark beside a part of the operation and request editors opens that part's. Anyone who reaches the server can read /help/, signed in or not.
With REQLYN_WEB_DIR and REQLYN_WEB_URL set (docs/DEPLOYMENT.md), the server's address opens Reqlyn in a browser. "Sign in" sends you to the server's identity provider and back; you come back to the page you were on, signed in for as long as a session lasts, in the workspace your role is in. While you use the page, the session is renewed before it ends, as long as the identity provider allows and at most a week from signing in: the server keeps the provider's refresh token for it, sealed, when the provider gives one for offline_access. When it cannot be renewed, or you have left the page alone, its last five minutes are said in the title bar, "Your session ends in N min.", with "Sign in again", which brings you back to the same page. Requests sends a request you write, from the server, or from the environment's agent when an agent carries it: choose its method, write its address ({{name}} takes the environment's variable of that name), add headers and a body, choose the environment and, as an operator or above, a credential it binds, and choose Send. What came back shows below it, and every request you send is in your history at the left, newest first, kept for 90 days and to your newest thousand; a credential's value and any header that carries one are kept as [masked]. The server refuses an address outside the destinations its operator allows, and says so.
Requests can be shared with the workspace: an editor names a request under SHARE WITH THE WORKSPACE, with a folder if wanted, and chooses "Save for the workspace". Everyone in the workspace then sees it under SHARED REQUESTS in the browser, and a desktop linked to the server under SHARED IN THE WORKSPACE, where it opens as a request of that computer's own. A shared request is kept as its definition: a credential is named, never its value, and a header value that looks secret is not kept. Two people saving the same one: the second is told someone saved it since.
Operations lists the workspace's drafts and opens one to change its name, description and owner, its inputs, its steps (each one's request, and the placeholders it fills from earlier steps) and its output. As a publisher, "Review and publish" shows what stops the draft, what changed since its latest version, what its callers would see and what each environment does not bind, and publishes the revision you reviewed as the next version; the Catalog then shows the version, where it runs, and "Activate in" an environment. An environment the deployment names under approval: waits for a second publisher, who approves or refuses the request on the same page. Canvas draws the draft as the desktop's canvas does, its steps as blocks and its actions as arcs, and builds it as the desktop's does: drag one of the workspace's requests in beside it to add a step that sends it (onto a wire, there; elsewhere, put where you let go; or choose it, after the last), drag a block onto a wire to move its step or anywhere else to put it there, drag a block's dot onto a block or End to draw an action (onto itself, a retry when it fails; onto another, going on there; onto End, ending), and right-click a block to open it, give it an action or remove it. "Arrange in a row" puts every block back in the row. With the keyboard: Enter opens a block, Delete removes it, Alt with an arrow moves it among the steps, Shift with an arrow moves it on the canvas. Where each block is is kept with the draft, so the desktop opens it as it was built; choose a block to open that step. Save keeps it as the next revision; if someone saved it since you opened it, the save is refused and you open it again. Each step also takes when it runs, a loop over a list an earlier step gave, its criteria, what happens when it succeeds or fails (go to a step, try again, end the run) and its scripts, as on the desktop. Paging, joins, messages, callbacks, undo, and a draft written as Arazzo, are changed on the desktop for now. It needs the editor role. A draft saved once is edited together: everyone with it open in a browser sees each other's edits as they are made, both kept, and Save saves a revision of what it then holds, everyone's edits, which every page then shows as saved. Each person's caret and selection shows in the field they are in, with their name; on the desktop, their name is beside the field, their selection quoted. The desktop, linked, edits it live too when what it has saved is the server's latest revision (the head says "live with the server"); its requests go when it saves and publishes, as before. Edits made on the desktop while the server cannot be reached are kept on this computer, even if it is closed, and merged with everyone else's when the server is back; its head says how many.
An administrator also has Administration: environments (variables, and credentials bound to secrets, whose values are set from a password field and never shown again), private agents (added with a token shown once, the environments each carries, revoked), members and their roles, notifications to Slack, Microsoft Teams or email, and the audit trail, newest first. Activity, on the rail, is what was done in the workspace (Activity). Set a credential's secret before saving the environment that binds it: the server refuses a binding to a secret it does not have.
Discovery drafts an operation from recordings: record the same task two or more times in your browser's developer tools, save each as a HAR file, choose them, name the operation and choose "Compare the recordings". The server says what calls they show, how values flow between them, what it inferred and assumed, and an example of each call with its secrets masked; "Save as the draft …" keeps the operation as a new draft, reviewed and published from the desktop for now. It needs the editor role, and the server must keep uploads (REQLYN_UPLOAD_DIR).
Your name, at the top, shows who you are, where you work and your role, and lets you choose Signal or Blueprint, light or dark, for this browser. "Sign out" ends the session.
The Catalog lists what the workspace has published; search it by name, description or owner. Choose an operation to read what it takes and gives, what a run of it may cost, its limits, the errors it can be refused or fail with, examples from its regression cases, and a snippet that calls it in Python, TypeScript, Rust, Go, C#, Java, PowerShell, Ruby, PHP, Kotlin, Swift or curl, with the command that writes that client (copy one and run it with REQLYN_SERVER set to the server's address and REQLYN_TOKEN to a service token), and what changed since an earlier version, each change that breaks a caller of it named. The page is the version's developer portal page, with Try it beside what it takes and gives. With a role that runs, try it: choose one of the environments it is activated in, fill in its inputs (the first example fills them) and choose "Run in <environment>". Once it ends, the page says how, with its output or why there is none; "Open the run" shows the run itself: each step, and a timeline of every request it sent. Runs lists the workspace's newest runs, and each opens the same way. An input that is a file is not taken in the browser yet: run such an operation from the desktop or the command line. The browser holds the session in a cookie its pages' scripts cannot read, and every change it asks for carries a token only the server's own page knows.
The developer portal
Each published version has a page for the people and programs that call it, read in the web client's Catalog by anyone with a role in the workspace (the desktop's Catalog shows its contract, routes and hosting, not the rest):
- What it takes and gives: its inputs and output fields with their kinds, from its contract.
- What a run may cost: its limits, and the most requests a run can send.
- Errors: the codes a call can be refused or fail with, each with what it means (error codes).
- Examples: from its regression cases, as they were kept, masked.
- Call it: a snippet in Python, TypeScript, Rust, Go, C#, Java, PowerShell, Ruby, PHP, Kotlin, Swift or curl, through the client
reqlyn remote sdkwrites, with the command that writes it. A snippet reads the server's address and a token fromREQLYN_SERVERandREQLYN_TOKEN: none holds a secret. - What changed: against an earlier version, each change that breaks a caller named.
The public portal
An administrator chooses "Make public" on a version's page ("Make private" takes it back; both are in the audit trail). The version is then in the workspace's public portal, /portal/<workspace>, which anyone reads without signing in: its contract, its limits, its errors, one example made from its schemas ("Its shape, from the schemas") and the snippets. It never shows a recorded value, who published it or an environment's name, and it runs nothing: calling the version still takes a service token.
reqlyn remote portal export --out <folder> writes the public portal as plain HTML and CSS, to put on any web server or open from the folder. It holds what /portal/<workspace> shows and nothing more, in the portal's look, with a search page.
A portal of its own
An administrator gives the portal a domain of its own, a title, a look (Signal or Blueprint, light or dark as the reader's system is) and an accent colour: in the web client's Administration, "Portal", or reqlyn remote portal set --domain docs.example.net --look blueprint --accent "#0b7a75". Point the domain at the server, through the proxy in front of it, keeping the host it was asked for (Host). On that domain the server answers with the portal alone: its index, a page for each public version, a search across them by name, description and id, its stylesheet and the search's script. Nothing else of the server answers there, no session is asked for and no cookie is set. The domain is a name (docs.example.net) the server's operator allows (REQLYN_PORTAL_DOMAINS, deployment), never the address the server is reached at, and one workspace's only; the server reads the domains anew within 30 seconds of a change made on another server.
Counts. Each page read on the domain adds one to its views that day, and each search one to the search page's searches. That is all that is kept: no address, no browser, no cookie, no query. Administrators read them in "Portal" or with reqlyn remote portal counts [--days <n>].
The OpenAPI description and clients
GET /v1/openapi.json describes the run interface of every version the caller may see, with its input and output schemas and the routes. reqlyn remote sdk --language python|rust|typescript|go|csharp|java|powershell --out <folder> writes a typed client from it, as a package ready to build (connectors).
Watching upstream APIs
- Drift: every response a version's steps receive is counted by its shape (field names and types, never values). Against its first 20, a field gone or of another type, a new field, or a new status is reported, marked where the version reads it, with the other versions that call the same endpoint. Each step is said to be confirmed, suspected, steady, not exercised or learning, with the signs.
reqlyn remote drift <operation> <version>, or the Catalog's Drift tab. - Against the description: a version published with its Arazzo source is also compared with the OpenAPI descriptions it was imported with.
- Alerts:
reqlyn remote webhook <address>posts each change to a place a version reads, once. - Impact of a newer description:
reqlyn remote impact newer.yaml --source inventorysays what a newer description of an upstream API would change for each published version whose source names it, and ends with 1 when a run could fail. - Versions compared:
reqlyn remote changes <operation> 2 3. - Migrating:
reqlyn migrate "<operation>" newer.yaml --source inventorysuggests what to read in place of each field the newer description drops, and--apply allsaves them as the next revision and replays its cases. In the desktop, "Migrate to a newer description…" in the Arazzo source does the same.
Recovering a failed run
reqlyn remote resume <run> resumes a failed run from the step it failed at, as a new run, the steps before it answered from what they received; a step that writes is sent again only with --yes. reqlyn remote undo <run> <step> --yes sends a step's undoing request, once. See Testing and recovery.
Private agents
An API the server cannot reach is called by a private agent inside that network. It connects out to the server over mutual TLS with its own token, takes the runs of the environments the manifest assigns it, and is given only the credentials each run names.
reqlyn remote agent add site-a
reqlyn remote agents
reqlyn remote agent revoke site-a
The token is printed once. Settings > Agents adds and revokes them too. A run whose agent is not heard from for two minutes fails with AGENT_LOST and is not sent again. Setting an agent up at its site is in DEPLOYMENT.md.
Threads
Any member can comment on what they can read: a draft or one of its steps (an editor and up, as reading a draft needs), a published version or a run or one of their steps, or a drift finding. Through the API, POST /v1/threads with on (drafts/check-device/steps/device, operations/check-device/versions/3, runs/<run>, operations/check-device/versions/3/drift/device/200/hostname) and body opens a thread; @user-29 in a comment mentions that member. GET /v1/threads?on=drafts/check-device lists every thread on the draft and its steps. Only a comment's author changes it or removes it; a removed comment stays, marked, without its text. Whoever opened a thread, or anyone who may edit, resolves it (PUT /v1/threads/<id>/resolution). The audit trail records each change, never what was said.
In the browser, a draft's "Threads" view, and the foot of a version's page and of a run's page, show the threads there and open new ones on the whole or a step. A thread opened on a run, or on a step of one, keeps what the run did as it stood then, its trace masked as the run's record is; one opened on a drift finding keeps the change found there. What a thread keeps stays with it after the run's record is swept or the drift moves on. On the desktop, linked to the server, a saved operation's "Threads" opens the threads on its server draft (the draft is sent by reviewing it for publishing), and a version in the Catalog has a Threads tab; in its Drift tab, "Comment…" beside a change opens a thread on that finding.
Activity
Activity, in the browser's rail, lists what happened in the workspace, newest first: drafts saved, versions published, activations asked for, approved, refused and made, threads opened, answered, resolved and reopened, and drift the server found. Each line goes to where it happened. Filter it by kind, by who (user:<subject> or a token's id) or by operation. You see only what you may read: an operation outside your reach is left out, and what happened on a draft is left out for those who cannot read drafts. What a comment says is never in it; follow the line to the thread. Through the API: GET /v1/activity?kind=thread&operation=check-device.
Notifications
An administrator points the workspace's Slack and Teams channels at their incoming webhooks in Administration, Notifications: name the secret that holds the webhook's address, set its value (write-only: it is never shown again), tick what the channel is told of (mentions, activations waiting for approval, activations approved or refused, drift found, scheduled runs that failed) and Save. The server posts only to addresses its operator allows, so add Slack's or Teams' webhook host to REQLYN_ALLOWED_DESTINATIONS (https://hooks.slack.com, your Teams workflow's host). A message says who did what and links to it in the web client; it never holds what a comment says. Each is sent once: one that fails is recorded under Latest deliveries and not sent again. Through the API: PUT /v1/notifications/channels/slack with secret and kinds; GET /v1/notifications/deliveries.
Each person chooses what they are emailed of on their account page: mentions of them, activations waiting for their approval (publishers), decisions on activations they asked for, and drift and failed scheduled runs in operations they reach. Mail goes only to the address their identity provider gives for them. The server sends it through the relay its operator sets:
REQLYN_SMTP_URL=smtps://[email protected] # or smtp://… (STARTTLS), or smtp+plain://127.0.0.1:25 for a local relay only
REQLYN_SMTP_PASSWORD_FILE=/etc/reqlyn/smtp-password # when the address names a user
REQLYN_SMTP_FROM=Reqlyn <[email protected]>
Presence
A draft or a version open in a browser shows who else has it open, under its name, and "editing" beside anyone holding changes not saved. Only those who may read it see it. A window that closes, or stops answering, is gone within a minute. The desktop, linked to the server, shows the same under an operation's name in the editor and under a version's heading in the Catalog, and tells the server what it has open. Through the API: GET /v1/presence?on=drafts/check-device, or follow GET /v1/presence/stream?on=… (server-sent events).
Shared sessions
A test can be shared while it runs, so that others follow it live: its steps, each request line and status, and its pauses arrive as they happen, masked, never a body. Only whoever shared it tells it or ends it; anyone who reaches the operation finds it in Runs, under LIVE NOW, and follows it read-only, or, on a draft or a version, chooses "Follow" beside the name of whoever shares it. The desktop, linked, does the same: "Follow" beside a name in an operation or the Catalog opens the session in Runs, where LIVE NOW lists the sessions shared now; "Back to the runs" leaves it. On the desktop, "Share this test" in a saved operation's Test run part shares its tests (Testing and recovery). Through the API: POST /v1/shares with kind, operation and title; POST /v1/shares/<id>/events with one event; PUT /v1/shares/<id>/end; follow GET /v1/shares/<id>/stream (server-sent events).
A workspace's lint rules
A draft is held to the workspace's lint rules in its publication review ("Publish…" on the desktop, "Review and publish" in the browser): its operation and requests by Reqlyn's own rules, and each OpenAPI or AsyncAPI description of its Arazzo source by Spectral's, each rule by its formats (lint rules). An error is among what stops the draft, and publishing is refused while it stands; a warning, an info or a hint is listed under the workspace's rules. Until an administrator sets a ruleset, Reqlyn's own rules hold, none above a warning, so nothing that published before is stopped. PUT /v1/lint-ruleset with {"ruleset": "<a ruleset as Spectral writes them>"} sets one (an administrator); it extends only the built-in sets, spectral:oas, spectral:asyncapi and reqlyn:operations, there being no file beside it on a server. extends: reqlyn:operations holds Reqlyn's rules as designed, a secret header written into a request then an error. GET reads it, DELETE removes it; setting and removing are in the audit trail. A secret header written into a request is masked when the draft is kept, so the request goes without it: the rule says so.
The API inventory
The server keeps a workspace's API descriptions in one place, its inventory (GET /v1/inventory, for anyone in the workspace): each OpenAPI or AsyncAPI description it registers, and each one its drafts and the latest published version of each operation carry in an Arazzo source. An editor registers one (POST /v1/inventory/descriptions) under a name, and an owner if it is to have one, by exactly one of:
url: its address, read at once and then again every day, or as often as an administrator sets (PUT /v1/inventory/settingswith{"read_every_hours": 1 to 720}), and whenever an editor asks (POST /v1/inventory/descriptions/<id>/read). It is read as the server sends a request, only from the destinations its operator allows (REQLYN_ALLOWED_DESTINATIONS); one that cannot be read keeps the text last read and says why.text: the file itself, at most 8 MiB, kept as given.git_path: its path in the repository of the workspace's Git source, read each time the source is taken.
Each description is listed by name with what it says it is (its title, version and format), where it comes from, who answers for it and its lint score. Its owner is the one set (PUT /v1/inventory/descriptions/<id>/owner; empty to go by the description), or else the one it names: x-owner, or its contact's name. Its score is 100, less 10 for each error the rules find in it, 3 for each warning and 1 for each info, never below 0; GET /v1/inventory/descriptions/<id> lists the findings. The rules are the workspace's lint rules, or Spectral's own (spectral:oas and spectral:asyncapi) until it sets some, and the inventory says which. A description carried in sources is one entry for each title, naming the operations that carry it; a registered description of the same title stands for it. Registering, removing (DELETE), setting an owner and the settings are in the audit trail.
For an OpenAPI description the inventory also says how it is used:
-
Endpoints: how many it describes, a method of a path each.
-
Users: each operation, by its draft and its latest published version, whose Arazzo source carries the description, or a request of whose steps reaches one of its endpoints, each marked by which (both, often). A request reaches an endpoint by its method and its address's path under one of the description's servers; a
{{placeholder}}stands for a path's{parameter}, and a server whose host is a variable, or a request whose host is, for any host. Each user names its latest version and how many regression cases it has. -
Coverage: the share of its endpoints that a user with regression cases sends a request to.
-
Drift: the worst drift of its users' latest versions at the steps that send to it:
confirmed,suspected,not_exercised,steadyorlearning. -
Health: the requests runs sent to its endpoints over the last 7 days, or as many days as an administrator sets (
health_daysin the settings, 1 to 90): how many, how many were answered below 400, and the 95th percentile of their time. -
Unused endpoints: each endpoint with the requests that reached it over the last 30 days, or as many as an administrator sets (
unused_daysin the settings, 1 to 365), and the last of them; one none reached is unused, and the description counts them.
The traffic its descriptions do not account for, over the same days (GET /v1/inventory/traffic), from the workspace's runs, its agents' work and the requests people send through the server: an undocumented endpoint is a method and a path (each number, UUID or long hexadecimal run read as {id}) on a host one of its descriptions names that none of them describes, with how many requests, when first and last, and whether runs, sends or agents made them; a host no description names is summed up, its requests and paths, rather than listed. A request whose host is an environment's variable, as a send's may be, is left out: where it went is not known.
On the desktop, linked to the server, Inventory on the rail lists them in its sidebar with the same filters and shows the one chosen beside them, with "Register…" at the sidebar's head. Both show each description's endpoints with their last request or as unused, and the undocumented traffic: on the desktop as "Undocumented traffic" at the head of the list, in the browser under the table. The desktop adds what this computer itself sent over the same days, from its own history: it is matched on the computer against the descriptions' servers and endpoints (GET /v1/inventory/endpoints lists them, without the descriptions), and none of it is sent to the server. A recording is not kept once it is reviewed, so it counts only as the requests sent from it. In the browser, Inventory lists them with filters (words, where they come from, and those needing attention: a score under 70, drift confirmed or suspected, fewer than 95% of requests answered, or a description not read) and opens each on its own page: its findings and users, and for an editor its owner, "Read it again" and "Remove…". An editor registers one there with "Register a description…".
The audit trail
Every change to a workspace is an audit event: who, what, to what, when, and never a secret, token, input or body. Administrators read it in Settings > Audit trail, or with reqlyn remote audit [--actor <who>] [--action <what>] [--json]. The trail is a hash chain the server's operator verifies with reqlyn-server audit verify.
Claude assistance on a server
An administrator can let a workspace ask Claude to explain tasks drafted from recordings: reqlyn remote assistance on --secret <id>, the Anthropic key being a workspace secret. Only a task's shape is ever sent. reqlyn remote demonstrate a.har b.har --explain prints what would be sent, and --yes sends it; nothing suggested is applied.
The assistant on a server
With a workspace's Claude assistance on, an editor holds a chat with the assistant over the workspace's drafts (POST /v1/assistant/chats, then POST /v1/assistant/chats/<id>/messages with {"text": …}). It lists and reads the drafts (each request's address and body with any secret masked, every secret header's value masked) and proposes each change: a new draft with its first step and output, a step sending a new request, an input, an output. Nothing is saved until the chat's person keeps a proposal (…/proposals/<p>/keep, or …/reject); a kept change is saved as the draft's next revision, and keeping it is in the audit trail (assistant.proposal.kept). It refuses to write a secret into a request: the environment binds a credential by its name. A chat is its person's own; another caller cannot read it. What is sent goes to the model the workspace's assistance names, and the chat says so. In the browser, an editor opens it with the robot button in the header: the panel at the right holds the chat, each proposal with Keep and Reject.
A failed run is diagnosed in a chat (POST /v1/assistant/chats/<id>/diagnose with {"run": …}): its record is said as the chat's next message, so its person sees what the model is told (the operation, the run and its version, why it failed, how each step ended, and, when the version keeps bodies, what each step last received with every secret-named value masked). The assistant says where it failed and proposes the fix, an output read from another path for instance, for the operation's draft; when the operation has no draft, keeping the fix makes one from the failed version. In the browser, "Diagnose" on a failed run's page does this in the assistant's panel. A load run is diagnosed the same way ({"load": …}): the assistant is told its profile, its runs ended, succeeded and failed, the latency of a run, and each step's latency and errors, and may propose a new load run with another profile or pacing; it starts only when an operator or above keeps it. GET /v1/loads lists the workspace's load runs the caller reaches, newest first. In the browser they are under Runs, each with a page of its own and, when something failed, "Diagnose".
Help for Reqlyn 0.5.1. All help topics