Glossary

The vocabulary nightjar uses, in plain language. Terms that describe something planned but not yet built are marked (Target) — everything else is shipped and works today.

Core

Cloud browser — a real browser that runs on nightjar’s infrastructure (not on your machine). Your agent drives it remotely. This is the heart of the product.

MCP (Model Context Protocol) — the HTTPS tool endpoint your agent speaks to. You point your agent host at https://api.nightjar.cloud/mcp with a Bearer token and the nightjar tools (session_start, navigate, perceive, act, screenshot, …) appear.

Session — one run of a cloud browser. You session_start, then navigate / perceive / act, and session_end when done. Each session is independently recorded.

Agent — the durable driver of sessions. An agent-bound API key carries the agent’s template (instructions, defaults), so a session inherits it with zero client config.

Perception & memory

Perception — what the agent reads instead of raw HTML: an accessibility tree plus visual and DOM enrichment, so the agent experiences the page closer to how a person does.

Journal / replay — every session is recorded as a durable journal you can replay later, with the authority decisions behind each operation. This is the audit + review surface.

Reaching your own machine

Network — a named set of hosts that a daemon makes reachable to authorized sessions — e.g. your dev laptop, an office LAN, or a CI runner. A session links whichever network it needs.

Daemon — a small program you run on your own machine (or in your network). It joins a network and relays traffic so a cloud browser can reach hosts only you can see. The daemon is a dumb relay: it holds your network’s join token, and that token never leaves it.

Tunnel — the relay path the daemon provides, carrying cloud-browser traffic back to your localhost / LAN.

Egress (split / local) — a session setting for where its network traffic goes: out to the public internet directly, or through your daemon to reach your private hosts.

Reach Grant — the user-facing local-reach object: this actor may reach this local target, through this daemon, for this long. Narrower than a network (one host and port) and owned by whoever created it. An agent self-provisions one with local_reach_ensure; you serve it with nightjar tunnel up <port>, or claim an agent’s with --claim njrg_…. Designed in ADR-035 and built — a network is now the internal primitive beneath it.

(Target) One-line install — the signed brew / curl | sh / winget bundle that would replace build-from-source is not built yet, which is the only reason local reach reads partial rather than today.

Identity, credentials & access

Identity — a virtual person a session can assume: it owns credentials, a persona, and logged-in auth-state. It is who the browser is on the web, and the agent acts as the identity without ever seeing the secrets. Not to be confused with a principal (below).

Principal — who is driving: the actor holding authority on the platform — a human, an agent, a service, or a key. A principal is the caller; an identity is a thing a caller may be allowed to embody. They are different entities with different ids, and every session records both.

The two planes — the load-bearing separation in nightjar’s authority model. They are not two kinds of credential; they are two different questions, and they never cross:

• Plane 1 — platform identity: who may drive. Your API key or OAuth token, the scopes it carries, the grants that let it assume an identity, and the per-operation authorization decision. This is the plane your agent authenticates on.
• Plane 2 — the site-credential vault: the secret the model never sees. The password or TOTP seed a site asks for, encrypted at rest (KMS), bound to an origin allowlist, and filled on the node at run time. The agent names a credential slot; there is no field on the API through which a stored secret can be returned to it.

The invariant that joins them: holding a Plane 1 credential never implies Plane 2 use. Being allowed to drive a session is not being allowed to spend an identity’s secrets on a site — that needs a grant, and the origin is checked at the moment of the fill.

Grant — a scoped, revocable delegation of capability from one principal to another. Revoking a grant force-closes any live use of it.

Scope — a single permission on an API key, drawn from a closed <resource>:<permission> registry (e.g. sessions:write, networks:write). Every API endpoint checks the scopes its caller carries.

Capture & safety

Capture tier (NetworkLogTier) — how much of a session’s network traffic is recorded: Off, Metadata, Headers, or Full. The tier is the control: it decides what is captured at all, and what a tier withholds at capture time is never recoverable afterwards.

Value-free (and what it does not cover) — a platform-held secret is never returned by any API or tool. A vault credential is filled on the node and zeroized; there is no field on the wire through which its value can come back, and the audit records that it was used, never the value. This guarantee is about secrets nightjar holds — not about what the page itself shows. Content your browser displays or copies — captured request/response bodies, clipboard reads, extracted text, console output, downloaded file names — reaches your agent verbatim. There is deliberately no content-shape filter guessing at which strings look secret: shape-matching could not catch a short password and destroyed ordinary text that merely looked like a token, so it was removed rather than left as a guarantee nobody could rely on. Choose the capture tier with that in mind, and treat captured session data as sensitive by default.

Egress floor — a per-network allowlist of declared hosts plus a never-allow floor, designed so a cloud browser only reaches hosts a network has declared (governed by ADR-021). The declared-host enforcement is a deployment-gated capability.

Missing a term? The deeper detail lives in the guides, and the exact field-level contract in the API reference. This page is the quick reference; it stays in lockstep with what’s actually shipped.