> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/agent-pro-entitlements.md). # Agent Pro entitlements and usage ## Boundary An Agent Pro license enables credential issuance. A version-1 `nsl_v1` license and its credentials remain proposal-only. The additive version-2 `nsl_v2` automation add-on carries a separate monthly automation-attempt allowance and is required before an operator may bind one active credential to a revocable Hyperliquid-testnet policy using [`agent-automation.md`](/nytshift-docs/agents-identity-and-data/agent-automation.md). The add-on alone never enables the signer, and the credential never becomes wallet or signer authority. The issuer private key belongs to NIGHTSHIFT's commercial operator and must never enter the repository, web process, browser, backup bundle, prompt, analytics or customer machine in a hosted distribution. The current repository provides manual, provider-neutral license issuance. It does not collect payment. Issue a license only after the separate billing/customer process has made that decision. ## Create the issuer key once Choose paths outside the repository and customer runtime. On a dedicated issuer machine: ```powershell $env:NIGHTSHIFT_AGENT_LICENSE_PRIVATE_KEY_PATH = "$env:USERPROFILE\.nightshift-license-authority\agent-pro-private.pem" $env:NIGHTSHIFT_AGENT_LICENSE_PUBLIC_KEY_PATH = "$env:USERPROFILE\.nightshift-license-authority\agent-pro-public.pem" node scripts/agent-license.mjs keygen ``` The command refuses overwrite. Back up the private key through a separate protected secret-management workflow. Losing it prevents renewal; leaking it requires immediate key rotation and revocation of every license signed by that key. ## Issue one entitlement Use an opaque customer UUID from the external billing system when available. Omitting it generates a new subject UUID: ```powershell node scripts/agent-license.mjs issue --subject 11111111-1111-4111-8111-111111111111 --days 30 --max-agents 3 --monthly-attempts 10000 ``` That command issues a proposal-only `nsl_v1` license. To sell the automation add-on, issue an additive v2 license with both allowances: ```powershell node scripts/agent-license.mjs issue-automation --subject 11111111-1111-4111-8111-111111111111 --days 30 --max-agents 3 --monthly-attempts 10000 --monthly-automation-attempts 1000 ``` The output includes the one-line signed license, opaque IDs, limits and public-key fingerprint. Deliver the license through a secret manager. Do not email it, place it in a URL or commit it. Never rewrite an existing v1 payload in place; renewal or upgrade receives a newly signed v2 license ID. ## Configure supervised localhost Stop the current supervisor before changing its inherited environment. Remove the issuer private-key path, then supply only the signed license, issuer public key and a distinct operator secret in the shell that starts NIGHTSHIFT: ```powershell pnpm local:stop $publicKeyPath = "$env:USERPROFILE\.nightshift-license-authority\agent-pro-public.pem" $env:NIGHTSHIFT_AGENT_PRO_LICENSE = "nsl_v1... or nsl_v2..." $env:NIGHTSHIFT_AGENT_PRO_PUBLIC_KEY = Get-Content -Raw $publicKeyPath $env:NIGHTSHIFT_OPERATOR_SECRET = [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(48)) Remove-Item Env:NIGHTSHIFT_AGENT_LICENSE_PRIVATE_KEY_PATH -ErrorAction SilentlyContinue Remove-Item Env:NIGHTSHIFT_AGENT_LICENSE_PUBLIC_KEY_PATH -ErrorAction SilentlyContinue pnpm local:start pnpm local:health ``` Do not put either runtime value in `~/.nightshift/config.json`; the validator rejects them. The public key is not secret, but keeping both values in the launch environment makes rotation explicit and avoids license/customer metadata in persistent configuration. ## Verify, meter and export The issuer machine can independently verify a delivered token: ```powershell $env:NIGHTSHIFT_AGENT_PRO_LICENSE = "nsl_v1... or nsl_v2..." $env:NIGHTSHIFT_AGENT_LICENSE_PUBLIC_KEY_PATH = "$env:USERPROFILE\.nightshift-license-authority\agent-pro-public.pem" node scripts/agent-license.mjs verify ``` After unlocking the operator session, Terminal **Safety settings → Pro Agent API** shows signed-license state, current UTC-month usage and active credential capacity. **Copy usage** retrieves the operator-only statement from `/api/agents/usage`. It contains opaque license/customer IDs and aggregate counters, so still treat it as private billing data. Every authenticated submission that reaches proposal policy evaluation counts, including schema-invalid, out-of-mandate and over-limit attempts. An MCP-backed request rejected for missing proposal mode or scope does not reach policy evaluation and does not count. Monthly proposal allowance is shared across all credentials bound to the license. For an `nsl_v2` add-on, every new automation request ID that reaches the atomic policy boundary after valid DPoP consumes one automation attempt. Policy rejections and over-limit attempts count. Exact replay returns the retained action without a second charge; changed-body request-ID conflicts and GET status/reconciliation do not count. Terminal **Agent Pro automation** shows the aggregate and **Copy automation usage** retrieves `/api/automations/usage`. Its statement contains only opaque license/subject IDs, aggregate counters and a content digest. It never includes an order body, account, key or token. This usage statement is exact only for the local NIGHTSHIFT installation that produced it. A hosted commercial launch must reconcile entitlements and usage through an authenticated central service before relying on cross-installation limits or invoices. ## Renewal, rotation and incident response * Renewal or an upgrade from proposal-only to automation should use a new license ID and an appropriate validity window. Restart the supervisor with the new token. * A changed license ID invalidates existing licensed credentials. Unlock, use **Revoke all**, then issue replacement credentials so durable audit records the transition. * For a leaked agent token, revoke it immediately; rotating the commercial license is not required unless the license token also leaked. * For a leaked license token, remove it from the runtime, stop customer agents, revoke all and issue a new license ID. * For an issuer private-key leak, stop issuance, generate a new key pair, distribute the new public key and licenses, and revoke every credential under the compromised authority. * An expired or absent license locks new issuance. A partial or invalid pair makes `/api/health` unsafe and the supervisor will not promote the child as healthy. The aggregate content digest is not a receipt or payment-provider signature. Connect a chosen checkout/webhook provider in a separate milestone; do not infer payment from local counters. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/agent-pro-entitlements.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.