CLI command
jeden headless
Serve the multi-tenant Jeden RPC service over a TLS listener where each client proves itself with a client certificate or with its Wisent identity.
Exact invocation#
jeden headless <addr> <server-cert.pem> <server-key.pem> <client-ca.pem> <identity-map.json> <limits.json> [revoked-serials.txt]Inputs and options#
- Required: bind address, server certificate chain, server private key, client CA bundle, a JSON identity map, and a JSON limits declaration.
- The limits declaration names every bound the host keeps; none is compiled in. It is one object with exactly these fields, each a whole number of at least one:
maxActiveRequestsandmaxSessions(per tenant),maxStoredBytes(bytes one tenant may store under the data root),workers(threads session work runs on),queue(jobs that may wait for a thread),replayEvents(events each session's replay keeps),maxFrameBytes(the largest frame a connection may send),maxConnections(connections served at once) andreconnectTtlSeconds(how long a reconnect token stays valid). - Optional: a text file of revoked client-certificate serials.
- Each identity-map entry supplies
tenantand eithersanwithprincipal(a client certificate) orwisentOrganization, a Wisent organization UUID whose members sign in with their Wisent identity. Either kind may supplyworkspaces: a list of absolute host directories that principal is granted. - When the map names at least one
wisentOrganization, the listener also finishes handshakes without a client certificate. Such a connection's first request must beidentity/authenticatewithaccessToken(the Wisent access token the person signed in with) andorganizationId. The daemon asks Wisent Identity (authorize_organizationon the identity project thatJEDEN_WISENT_AUTH_URLandJEDEN_WISENT_AUTH_ANON_KEYname; nothing is compiled in, and a map with awisentOrganizationentry refuses to start without them asJEDEN_WISENT_AUTH_URL is not set; Wisent Identity has no address) and answersprincipal(wisent-user:<user id>),tenant,organizationIdandrole. A certificate, when presented, is still verified exactly as before. - Host-wide model keys are optional and distinct from workspace grants. Set
JEDEN_CREDENTIAL_MANAGER_USER_IDto the Wisent user UUID that may manage this host's pool. Without it the token methods refuseaccess_denied; another member, even with a workspace grant, has no credential-management authority. - The same completion get, control and continue methods are available after session creation or open, subject to the existing tenant/workspace authorization. Continue uses the request metadata idempotency key and returns the same started, reattached or completed response as session/prompt.
- Jeden iOS closes established and still-authenticating connections when the signed-in user or selected organization changes. Pending callers receive the connection failure, and a late authentication result cannot restore the previous identity's socket. A subsequent request authenticates with the current shared Wisent session.
- The iOS host readiness badge accepts only the latest probe for the current identity. Identity changes and host removal invalidate pending results; cancelled probes clear their own pending badge without overwriting a newer request.
asks/list,asks/get {askId}andasks/answer {askId,text}return what the RPC methods of the same names return, without the host'sregisterpath. A principal sees an ask first asked in a workspace it is granted, or asked in a session it holds;asks/listleaves every other ask out, andasks/getandasks/answerrefuse itaccess_denied. An id the register does not hold is refused withjeden.completion.asks.answer.ask-unknown, naming the register and the asks it holds, and every other refusal of the register and the answer is its declaredjeden.completion.asks.*cause.token/statusreturns route, key source, token metadata and refusals without secrets;token/listreturns metadata;token/add {label,endpoint,token}stores a key on the host;token/remove {id}removes it. Jeden iOS presents these on the selected host's Model credentials screen and sends a new key only over its authenticated TLS connection.health/readinessreturns the executor state and the live daemon's embedded buildversion. A real host qualification compares its clean source revision to the version suffix; a reachable listener alone does not prove the changed daemon is running.
Output and state effect#
Creates .jeden/headless service state, a durable reconnect key, tenant idempotency/replay stores, and an mTLS listener at the requested address. Beyond health/readiness, session/create, session/reconnect, session/prompt, session/replay and session/cancel, it serves session/list, session/open and session/history: a principal with granted workspaces lists the host's own sessions whose recorded cwd lies inside a grant, opens one under its own host session id so later prompts continue that very ledger, and reads its replayed turns without resuming it. A principal without workspaces keeps seeing only the sessions it created here, jailed to its tenant scratch workspace.
Refusals and boundaries#
- Any argument count other than six or seven is refused with the exact usage line shown above (
jeden.rpc.headless.words-wrong, exit 2). - Every refusal of starting the listener is declared:
jeden errors show jeden.rpc.headlessandjeden errors show jeden.rpc.tlslist them, each naming the file it read. Limits that cannot be read (limits-unreadable), are not JSON (limits-not-json) or have a missing, zero, unknown or non-numeric field (limits-shapeless, quoting the JSON reader); an identity map that cannot be read, is not JSON, is of another shape or is empty (map-*); a mapping naming neither or both kinds (mapping-ambiguous, saying which fields it names), a principal or tenant that is no id (mapping-id-invalid), and a workspace that is relative, does not resolve or is no directory (workspace-*); a revocation list that cannot be read (revocations-unreadable); a data root under.jeden/headlessthat cannot be created; a reconnect key that cannot be read, created or written, or is shorter than 32 bytes (key-short, naming its length); a worker or the runtime that cannot start (exit 69); and an address in use (address-in-use, exit 69), of no host:port form (address-malformed, exit 2), denied or not this host's. Loading the TLS identity, at start and on every reload: a file that cannot be opened (naming its role: server certificate chain, server's private key, client CA bundle), a PEM block that cannot be read, a file with no certificate (its size) or no private key, a CA certificate no trust anchor can be made of, and a key that is not the certificate's (identity-mismatched). A private key's bytes are never shown. The real journey isJEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/headless.mjs. - Each connection's refusals are
jeden errors show jeden.rpc.connection, said on the daemon's standard error with the peer's address (the client sees a dropped socket) or answered as an error frame: a connection closed before its TLS preface, a plaintext preface (its first bytes named), a rejected handshake (no client certificate, one the CA did not issue, a TLS other than 1.3), nojeden.session.v1ALPN (naming what was offered), a revoked certificate (its serial), one without an identity SAN, and one whose SANs no identity-map entry names (san-unmapped, naming them); a frame overmaxFrameBytes(its size and the limit) or empty, answeredmalformed_frame; a frame that is not JSON or no request envelope, answeredmalformed_json; and a connection beyondmaxConnections, answeredbackpressure(retryable) before any TLS. The real journey isJEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/connection.mjs. - A
workspacesentry that is not an absolute path, contains.., or is not an existing readable directory is named and refused when the identity map is loaded. - An identity-map entry that names both
sanandwisentOrganization, or neither, is refused when the map is loaded. A certificate-less connection whose first request is notidentity/authenticateis answeredunauthenticatedand closed; a non-UUIDorganizationIdisinvalid_organization; a token Wisent Identity rejects isunauthenticated; a user who is not a member isforbidden; an organization the map does not name isaccess_denied; an unreachable Wisent Identity is the retryableidentity_unavailablecarrying the cause. - A non-Unicode or invalid
JEDEN_CREDENTIAL_MANAGER_USER_IDreturnscredential_configurationwith cause. An unset manager or another identity returnsaccess_deniedbefore reading token metadata or touching storage. Add and remove preserve the same invalid endpoint, duplicate label, unsafe store and unknown ID causes as the localjeden tokenRPC. session/openandsession/historyrefuseaccess_deniedfor a principal without granted workspaces, for an id that is not a session directory under the session root, and for a session whose recordedcwdlies outside every grant; a missing or blanksessionIdand alimitbelow one areinvalid_request.session/import {content}brings in a session transcript a client holds as a file rather than a path on the host (Jeden iOS from the Files app or another app's share sheet): the text is kept under the session root'simport-stagingfolder by its own SHA-256 and imported exactly asjeden import <path>imports it, so the same text sent again answers the session already imported; the answer is that import's. A principal without granted workspaces isaccess_denied, a missingcontentisinvalid_request, a transcript overmaxFrameBytesis the frame's own refusal, and an import that fails isimport_errorwith its cause.- A session whose ledger cannot be read is left out of
session/listand named in the reply'sunreadablelist as{sessionId, cause}, the cause being the read or parse error;skippedis the length of that list.session/openandsession/historyon such a session answer that cause too. - Tenant request, session, and stored-byte limits are enforced instead of admitting excess work.
- A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits
2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.