Jeden/Docs

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#

Shell
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: maxActiveRequests and maxSessions (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) and reconnectTtlSeconds (how long a reconnect token stays valid).
  • Optional: a text file of revoked client-certificate serials.
  • Each identity-map entry supplies tenant and either san with principal (a client certificate) or wisentOrganization, a Wisent organization UUID whose members sign in with their Wisent identity. Either kind may supply workspaces: 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 be identity/authenticate with accessToken (the Wisent access token the person signed in with) and organizationId. The daemon asks Wisent Identity (authorize_organization on the identity project that JEDEN_WISENT_AUTH_URL and JEDEN_WISENT_AUTH_ANON_KEY name; nothing is compiled in, and a map with a wisentOrganization entry refuses to start without them as JEDEN_WISENT_AUTH_URL is not set; Wisent Identity has no address) and answers principal (wisent-user:&lt;user id&gt;), tenant, organizationId and role. 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_ID to the Wisent user UUID that may manage this host's pool. Without it the token methods refuse access_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} and asks/answer {askId,text} return what the RPC methods of the same names return, without the host's register path. A principal sees an ask first asked in a workspace it is granted, or asked in a session it holds; asks/list leaves every other ask out, and asks/get and asks/answer refuse it access_denied. An id the register does not hold is refused with jeden.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 declared jeden.completion.asks.* cause.
  • token/status returns route, key source, token metadata and refusals without secrets; token/list returns 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/readiness returns the executor state and the live daemon's embedded build version. 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.headless and jeden errors show jeden.rpc.tls list 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/headless that 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 is JEDEN_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), no jeden.session.v1 ALPN (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 over maxFrameBytes (its size and the limit) or empty, answered malformed_frame; a frame that is not JSON or no request envelope, answered malformed_json; and a connection beyond maxConnections, answered backpressure (retryable) before any TLS. The real journey is JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/connection.mjs.
  • A workspaces entry 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 san and wisentOrganization, or neither, is refused when the map is loaded. A certificate-less connection whose first request is not identity/authenticate is answered unauthenticated and closed; a non-UUID organizationId is invalid_organization; a token Wisent Identity rejects is unauthenticated; a user who is not a member is forbidden; an organization the map does not name is access_denied; an unreachable Wisent Identity is the retryable identity_unavailable carrying the cause.
  • A non-Unicode or invalid JEDEN_CREDENTIAL_MANAGER_USER_ID returns credential_configuration with cause. An unset manager or another identity returns access_denied before reading token metadata or touching storage. Add and remove preserve the same invalid endpoint, duplicate label, unsafe store and unknown ID causes as the local jeden token RPC.
  • session/open and session/history refuse access_denied for a principal without granted workspaces, for an id that is not a session directory under the session root, and for a session whose recorded cwd lies outside every grant; a missing or blank sessionId and a limit below one are invalid_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's import-staging folder by its own SHA-256 and imported exactly as jeden import &lt;path&gt; imports it, so the same text sent again answers the session already imported; the answer is that import's. A principal without granted workspaces is access_denied, a missing content is invalid_request, a transcript over maxFrameBytes is the frame's own refusal, and an import that fails is import_error with its cause.
  • A session whose ledger cannot be read is left out of session/list and named in the reply's unreadable list as {sessionId, cause}, the cause being the read or parse error; skipped is the length of that list. session/open and session/history on 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) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: &lt;operation&gt;.&lt;cause&gt;, and jeden errors show &lt;operation&gt; lists every cause of that functionality.