# hasp full documentation bundle

Version: 1.0.39
Docs root: https://gethasp.com/docs/
Guides root: https://gethasp.com/guides/
GitHub: https://github.com/gethasp/hasp


================================================================================
Start / Overview
URL: https://gethasp.com/docs/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. A fresh MCP session holds no project lease, so send it on the first call against a repo. Without an active lease the call fails with project lease required. grant secret can be once, session, or window. Send it when a call fails with secret session grant required or access secret prompt required. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. One daemon serves one socket. Before it binds, a daemon takes an exclusive advisory lock on .lock in the runtime directory, so HASP HOME/runtime/daemon.sock is guarded by HASP HOME/runtime/daemon.sock.lock. A daemon that loses that race to a daemon already serving the socket exits 0 and touches nothing: not the socket, not daemon.pid, not daemon.http.port. If the lock is held but nothing answers on the socket, the loser waits up to three seconds for the holder to let go, since hasp daemon stop returns as soon as it has signalled the incumbent. Only after that does it give up, and then with an error naming both paths rather than a silent exit 0. The kernel holds the lock on an open file descriptor and drops it on every exit path including SIGKILL, so a leftover lock file never wedges the next start. Point HASP SOCKET at a different path to run a second daemon on purpose. If something is already listening on the socket but does not answer as a HASP daemon, HASP refuses to start and names the socket in the error. It will not unlink a live socket: the listener would keep serving an inode no client can reach and would never exit. Find the holder with lsof , stop it, or set HASP SOCKET elsewhere. The same rule covers a socket that simply did not answer in time. A command with a short deadline, such as an MCP preflight probe, can miss a busy daemon's reply. HASP re probes the socket on its own budget before treating it as stale, and waits the incumbent out instead of unlinking it and starting a replacement that would then lose the lock to the daemon it just made unreachable. A serving daemon re checks every 30 seconds that its socket path still resolves to the inode it bound. If another process unlinked the socket and took the name, the daemon shuts down instead of idling unreachable. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: HASP installs into Git's effective hooks directory for the current working tree. For linked worktrees, that is the common git directory; when core.hooksPath is set, HASP uses it only if it resolves inside the project or the git common directory. Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.39] Stop leaking daemon processes. Starting a daemon used to unlink the socket and its sidecar files before spawning, but unlinking a unix socket does not stop its listener: the incumbent kept serving an inode no client could reach, and had no path to exit. One machine accumulated 738 live daemons holding 10.87 GB of RSS. Make hasp daemon serve a singleton with an exclusive advisory lock on .lock. A daemon that loses the race exits 0 and touches no shared file. The kernel drops the lock on every exit path including SIGKILL, so a leftover lock file cannot wedge the next start. Refuse to unlink a socket that still has a listener. When something answers on the socket path but does not identify as a HASP daemon, the error now names the socket so the operator can find the holder with lsof or point HASP SOCKET elsewhere. Shut a daemon down when its socket is unlinked and replaced. A serving daemon re checks every 30 seconds that the socket path still resolves to the inode it bound, so a daemon that has been orphaned reaps itself. Delete shared runtime files only after proving ownership: inode compare for the socket, pid compare for daemon.pid, byte compare for daemon.http.port. A dying daemon no longer wipes a live one's runtime directory. Write daemon.pid from the daemon after it wins the lock instead of from the process that spawned it, so the file always names a daemon that is actually serving. Stop treating a dial that ran out of time as proof the socket is stale. A command with a short deadline, such as an MCP preflight probe, can miss a busy daemon's reply; HASP used to unlink the socket on that evidence and start a replacement, which then lost the singleton lock to the daemon it had just made unreachable, so nothing served the socket and the caller waited out its startup timeout. HASP now re probes the socket on its own budget and waits the incumbent out. Wait up to three seconds for the singleton lock instead of exiting the moment it is taken. hasp daemon stop returns once it has signalled the incumbent, so a daemon started right after a stop could lose the lock to a process on its way out. Losing the lock to a holder that is not serving is now an error naming both the lock and the socket, not a silent exit 0 that looks like a successful start. [v1.0.38] Describe grant project and grant secret in the advertised MCP tool schemas instead of labelling both "Audited grant choice". The schema now states that a fresh MCP session holds no project lease, what each scope covers, and which error each field resolves, so agents can send the grant on the first call rather than discovering it from a project lease required failure. Document the same first call lease contract in the agent mental model guide. Bring the published source tree back in line with the canonical repository, restoring the hook, runtime, and MCP test coverage that landed in v1.0.37. Raise Go modules and CI toolchain pins to 1.26.5 to clear the current Go stdlib OSV advisory before release. [v1.0.37] Install HASP pre commit and pre push hooks correctly from linked Git worktrees by resolving Git's common hooks directory instead of assuming .git/hooks exists under the worktree. Respect safe core.hooksPath values while refusing disabled, global, or symlink escaped hook directories that would make HASP report protection in a place Git will not actually use. Keep non Git project binds from recording hooks as installed when no hook installation happened. Extend MCP compatibility coverage so tools/call accepts reserved meta request fields and advertised tool schemas stay free of client rejected combinators. Make routine release preflights faster and less resource heavy by defaulting local readiness and the release driver to a bounded preflight while keeping the full release gate available on demand. [v1.0.36] Return standard MCP CallToolResult envelopes for tools/call, including text content and structured payloads, so strict clients such as Codex can execute HASP tools without Unexpected response type failures. Extend MCP tests and the release gate to require the tool call envelope before a release can ship. [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.39 (183c110b76) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable a process is listening on the socket path but does not answer as a HASP daemon, so HASP refuses to unlink it and start over What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy For the last trigger, the error names the socket path. Identify the holder with lsof and stop it, or point HASP SOCKET at a different path. HASP will not unlink a socket that still has a listener: the listener would keep serving an inode no client can reach and would never exit. The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.39/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.39/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.39/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.39/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. A fresh MCP session holds no project lease, so send it on the first call against a repo. Without an active lease the call fails with project lease required. grant secret can be once, session, or window. Send it when a call fails with secret session grant required or access secret prompt required. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.39/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.39/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.39/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.39/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. One daemon serves one socket. Before it binds, a daemon takes an exclusive advisory lock on .lock in the runtime directory, so HASP HOME/runtime/daemon.sock is guarded by HASP HOME/runtime/daemon.sock.lock. A daemon that loses that race to a daemon already serving the socket exits 0 and touches nothing: not the socket, not daemon.pid, not daemon.http.port. If the lock is held but nothing answers on the socket, the loser waits up to three seconds for the holder to let go, since hasp daemon stop returns as soon as it has signalled the incumbent. Only after that does it give up, and then with an error naming both paths rather than a silent exit 0. The kernel holds the lock on an open file descriptor and drops it on every exit path including SIGKILL, so a leftover lock file never wedges the next start. Point HASP SOCKET at a different path to run a second daemon on purpose. If something is already listening on the socket but does not answer as a HASP daemon, HASP refuses to start and names the socket in the error. It will not unlink a live socket: the listener would keep serving an inode no client can reach and would never exit. Find the holder with lsof , stop it, or set HASP SOCKET elsewhere. The same rule covers a socket that simply did not answer in time. A command with a short deadline, such as an MCP preflight probe, can miss a busy daemon's reply. HASP re probes the socket on its own budget before treating it as stale, and waits the incumbent out instead of unlinking it and starting a replacement that would then lose the lock to the daemon it just made unreachable. A serving daemon re checks every 30 seconds that its socket path still resolves to the inode it bound. If another process unlinked the socket and took the name, the daemon shuts down instead of idling unreachable. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.39/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: HASP installs into Git's effective hooks directory for the current working tree. For linked worktrees, that is the common git directory; when core.hooksPath is set, HASP uses it only if it resolves inside the project or the git common directory. Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.39/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.39/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.39/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.39/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.39/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.39/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.39] Stop leaking daemon processes. Starting a daemon used to unlink the socket and its sidecar files before spawning, but unlinking a unix socket does not stop its listener: the incumbent kept serving an inode no client could reach, and had no path to exit. One machine accumulated 738 live daemons holding 10.87 GB of RSS. Make hasp daemon serve a singleton with an exclusive advisory lock on .lock. A daemon that loses the race exits 0 and touches no shared file. The kernel drops the lock on every exit path including SIGKILL, so a leftover lock file cannot wedge the next start. Refuse to unlink a socket that still has a listener. When something answers on the socket path but does not identify as a HASP daemon, the error now names the socket so the operator can find the holder with lsof or point HASP SOCKET elsewhere. Shut a daemon down when its socket is unlinked and replaced. A serving daemon re checks every 30 seconds that the socket path still resolves to the inode it bound, so a daemon that has been orphaned reaps itself. Delete shared runtime files only after proving ownership: inode compare for the socket, pid compare for daemon.pid, byte compare for daemon.http.port. A dying daemon no longer wipes a live one's runtime directory. Write daemon.pid from the daemon after it wins the lock instead of from the process that spawned it, so the file always names a daemon that is actually serving. Stop treating a dial that ran out of time as proof the socket is stale. A command with a short deadline, such as an MCP preflight probe, can miss a busy daemon's reply; HASP used to unlink the socket on that evidence and start a replacement, which then lost the singleton lock to the daemon it had just made unreachable, so nothing served the socket and the caller waited out its startup timeout. HASP now re probes the socket on its own budget and waits the incumbent out. Wait up to three seconds for the singleton lock instead of exiting the moment it is taken. hasp daemon stop returns once it has signalled the incumbent, so a daemon started right after a stop could lose the lock to a process on its way out. Losing the lock to a holder that is not serving is now an error naming both the lock and the socket, not a silent exit 0 that looks like a successful start. [v1.0.38] Describe grant project and grant secret in the advertised MCP tool schemas instead of labelling both "Audited grant choice". The schema now states that a fresh MCP session holds no project lease, what each scope covers, and which error each field resolves, so agents can send the grant on the first call rather than discovering it from a project lease required failure. Document the same first call lease contract in the agent mental model guide. Bring the published source tree back in line with the canonical repository, restoring the hook, runtime, and MCP test coverage that landed in v1.0.37. Raise Go modules and CI toolchain pins to 1.26.5 to clear the current Go stdlib OSV advisory before release. [v1.0.37] Install HASP pre commit and pre push hooks correctly from linked Git worktrees by resolving Git's common hooks directory instead of assuming .git/hooks exists under the worktree. Respect safe core.hooksPath values while refusing disabled, global, or symlink escaped hook directories that would make HASP report protection in a place Git will not actually use. Keep non Git project binds from recording hooks as installed when no hook installation happened. Extend MCP compatibility coverage so tools/call accepts reserved meta request fields and advertised tool schemas stay free of client rejected combinators. Make routine release preflights faster and less resource heavy by defaulting local readiness and the release driver to a bounded preflight while keeping the full release gate available on demand. [v1.0.36] Return standard MCP CallToolResult envelopes for tools/call, including text content and structured payloads, so strict clients such as Codex can execute HASP tools without Unexpected response type failures. Extend MCP tests and the release gate to require the tool call envelope before a release can ship. [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.39/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.39/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.39/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.39/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.39 (183c110b76) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.39/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable a process is listening on the socket path but does not answer as a HASP daemon, so HASP refuses to unlink it and start over What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy For the last trigger, the error names the socket path. Identify the holder with lsof and stop it, or point HASP SOCKET at a different path. HASP will not unlink a socket that still has a listener: the listener would keep serving an inode no client can reach and would never exit. The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.38/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.38/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.38/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.38/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. A fresh MCP session holds no project lease, so send it on the first call against a repo. Without an active lease the call fails with project lease required. grant secret can be once, session, or window. Send it when a call fails with secret session grant required or access secret prompt required. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.38/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.38/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.38/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.38/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.38/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: HASP installs into Git's effective hooks directory for the current working tree. For linked worktrees, that is the common git directory; when core.hooksPath is set, HASP uses it only if it resolves inside the project or the git common directory. Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.38/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.38/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.38/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.38/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.38/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.38/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.38] Describe grant project and grant secret in the advertised MCP tool schemas instead of labelling both "Audited grant choice". The schema now states that a fresh MCP session holds no project lease, what each scope covers, and which error each field resolves, so agents can send the grant on the first call rather than discovering it from a project lease required failure. Document the same first call lease contract in the agent mental model guide. Bring the published source tree back in line with the canonical repository, restoring the hook, runtime, and MCP test coverage that landed in v1.0.37. Raise Go modules and CI toolchain pins to 1.26.5 to clear the current Go stdlib OSV advisory before release. [v1.0.37] Install HASP pre commit and pre push hooks correctly from linked Git worktrees by resolving Git's common hooks directory instead of assuming .git/hooks exists under the worktree. Respect safe core.hooksPath values while refusing disabled, global, or symlink escaped hook directories that would make HASP report protection in a place Git will not actually use. Keep non Git project binds from recording hooks as installed when no hook installation happened. Extend MCP compatibility coverage so tools/call accepts reserved meta request fields and advertised tool schemas stay free of client rejected combinators. Make routine release preflights faster and less resource heavy by defaulting local readiness and the release driver to a bounded preflight while keeping the full release gate available on demand. [v1.0.36] Return standard MCP CallToolResult envelopes for tools/call, including text content and structured payloads, so strict clients such as Codex can execute HASP tools without Unexpected response type failures. Extend MCP tests and the release gate to require the tool call envelope before a release can ship. [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.38/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.38/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.38/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.38/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.38 (0e074f5160) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.38/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.37/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.37/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.37/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.37/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.37/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.37/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.37/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.37/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.37/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: HASP installs into Git's effective hooks directory for the current working tree. For linked worktrees, that is the common git directory; when core.hooksPath is set, HASP uses it only if it resolves inside the project or the git common directory. Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.37/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.37/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.37/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.37/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.37/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.37/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.37] Install HASP pre commit and pre push hooks correctly from linked Git worktrees by resolving Git's common hooks directory instead of assuming .git/hooks exists under the worktree. Respect safe core.hooksPath values while refusing disabled, global, or symlink escaped hook directories that would make HASP report protection in a place Git will not actually use. Keep non Git project binds from recording hooks as installed when no hook installation happened. Extend MCP compatibility coverage so tools/call accepts reserved meta request fields and advertised tool schemas stay free of client rejected combinators. Make routine release preflights faster and less resource heavy by defaulting local readiness and the release driver to a bounded preflight while keeping the full release gate available on demand. [v1.0.36] Return standard MCP CallToolResult envelopes for tools/call, including text content and structured payloads, so strict clients such as Codex can execute HASP tools without Unexpected response type failures. Extend MCP tests and the release gate to require the tool call envelope before a release can ship. [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.37/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.37/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.37/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.37/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.37 (230f54ff82) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.37/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.36/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.36/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.36/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.36/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.36/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.36/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.36/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.36/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.36/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.36/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.36/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.36/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.36/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.36/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.36/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.36] Return standard MCP CallToolResult envelopes for tools/call, including text content and structured payloads, so strict clients such as Codex can execute HASP tools without Unexpected response type failures. Extend MCP tests and the release gate to require the tool call envelope before a release can ship. [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.36/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.36/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.36/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.36/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.36 (aebf66ddff) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.36/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.35/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.35/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.35/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.35/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.35/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, workspace trust, cookie, cookies, localStorage, sessionStorage, indexedDB, browserSession, browser session, browserSessionState, or browser session state local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret, public config, or browser session. browser session documents cookies, browser storage, or session state as high risk auth material. HASP rejects target delivery for that class until an explicit high risk capability path exists. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret, public config, or browser session. browser session requirements can be declared but cannot be delivered by manifest targets. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.35/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.35/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.35/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.35/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.35/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.35/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.35/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.35/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.35/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.35/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.35] Add the Agent Cookie comparison page to the public competition matrix. Classify cookies, browser storage, and browser session state as high risk manifest material. Allow value free browser session requirement declarations while rejecting manifest target delivery until HASP has an explicit high risk capability path. Reject raw cookie, localStorage, IndexedDB, and browser session value fields in repo manifests. [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.35/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.35/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.35/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.35/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.35 (bd6ba04488) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.35/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.34/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.34/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.34/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.34/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.34/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.34/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.34/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.34/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.34/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.34/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.34/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.34/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.34/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.34/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.34/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.34] Prevent managed Claude Code and Codex CLI MCP wrappers from being pinned to stale HASP AGENT HASP binaries, and make the release gate fail when generated MCP configs or wrapper ordering could shadow the managed binary. Make hasp run release gate coverage execute through a managed wrapper with a deliberately stale inherited HASP SESSION TOKEN, proving MCP session recovery before a tag ships. Teach hasp doctor and the MCP release gate to detect already running stale agent MCP bridge processes, report exact PIDs, and tell operators to restart the affected agent session instead of retrying a dead MCP connection. [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.34/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.34/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.34/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.34/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.34 (2d3464af47) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.34/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.33/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.33/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.33/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.33/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.33/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.33/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.33/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.33/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.33/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.33/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.33/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.33/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.33/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.33/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.33/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.33] Recover MCP tool calls from stale inherited HASP SESSION TOKEN values, including sessions that no longer exist or point at a different project. Keep explicit MCP session token values fail closed while returning a clear diagnostic that tells agents to omit stale explicit tokens and let HASP open a fresh local MCP session. Restore release blocking 100% Go statement coverage after the MCP hardening work and refresh the public export mirror. Raise Go modules to 1.26.4 to clear current Go stdlib OSV advisories before release. [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.33/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.33/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.33/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.33/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.33 (fff66c6e02) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.33/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.32/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.32/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.32/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.32/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.32/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which atomic refs belong to the same credential set? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. credential sets: the repo can name coupled roles, such as a Google OAuth client id and client secret, while keeping each value as its own ref. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. credential sets credential sets groups related requirement refs by role without storing a combined secret value. The google oauth client kind requires: client id: kv, public config client secret: kv, secret redirect uri: optional kv, public config The generic kind accepts any lowercase role names that point at existing requirements. Use generic only when HASP has no built in schema for the credential shape. Targets deliver individual roles from a set: from set plus role is mutually exclusive with ref. A delivery entry must use either a direct ref or a set role, never both. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.32/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.32/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.32/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.32/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.32/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.32/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.32/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: shipped in HASP v1.0.32. HASP models coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Manifest shape Use normal references and requirements for each atomic value, then declare the relationship in credential sets: Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: hasp project targets, hasp project requirements target, hasp project examples, hasp project doctor, hasp run target, hasp inject target, and MCP target tools resolve set backed delivery to the member refs before authorization. Agents see refs, roles, and set names, not plaintext values. Shipped set kinds google oauth client is schema checked: client id is required and must be a kv requirement classified as public config. client secret is required and must be a kv requirement classified as secret. redirect uri is optional and must be a kv requirement classified as public config when present. generic accepts any lowercase role names that point at existing requirements. Use it when HASP has no built in schema yet, while keeping each member's classification and kind on the requirement. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Target review includes the resolved member refs through the target signature. Changing a set member mapping changes the target's resolved refs and requires renewed local review before brokered execution can authorize the target. A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET generated .env example with placeholders only workspace visible generated files only through explicit target review and workspace output commands Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.32/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.32/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.32/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.32] Ship credential sets in value free manifests, including schema validation for google oauth client, set role target delivery through from set and role, project command output, MCP target metadata, brokered execution, and regression coverage. [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.32/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.32/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.32/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.32/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.32 (c6f5637c2d) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.32/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.31/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.31/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.31/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.31/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.31/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.31/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.31/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.31/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.31/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.31/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.31/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / Credential sets
URL: https://gethasp.com/docs/v1.0.31/credential-sets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/credential-sets.md
--------------------------------------------------------------------------------

Credential sets Status: scoped design. Credential sets are not a shipped manifest field in HASP v1.0.31. HASP should model coupled credentials as typed credential sets, not as one opaque stored secret. The motivating example is a Google OAuth web client. A working app usually needs a client id, a client secret, and at least one redirect URI. Those values are coupled because they describe one provider side client, but they do not all have the same sensitivity, delivery shape, or rotation behavior. The vault should keep the values atomic. The credential set should describe how those atomic values fit together. Decision Use a typed recipe over normal vault items: The shape above is illustrative, not accepted by current HASP releases. Each member remains a normal HASP item: GOOGLE CLIENT ID: key value item, often public config GOOGLE CLIENT SECRET: key value item, secret GOOGLE REDIRECT URI: key value item, public config Targets should deliver roles from the set, not blindly deliver the whole set: The delivery recipe can also assemble a provider shaped temporary file during a brokered run. That assembled file is an execution artifact, not the canonical stored value. Why not store a group as one secret An opaque JSON secret is convenient, but it is the wrong default for HASP. It loses field level classification. In OAuth, client id identifies the client, while client secret authenticates it. Treating both as the same secret forces the stricter policy onto harmless config or accidentally weakens the secret. It breaks independent rotation. Google client secret rotation can add a new secret, migrate traffic, and disable the old secret while the client ID stays stable. A blob makes that lifecycle harder to represent and audit. It widens grants. A caller that only needs client id should not receive client secret because the two happened to be stored together. It weakens redaction and audit. HASP should be able to report that a target used the client secret role without exposing the value or confusing it with the client id role. External constraints Google's OAuth web server documentation treats the downloaded client secret.json as client credentials, tells operators to store it securely, and says to keep it outside the source tree when code is shared: . Google's OAuth setup guidance also describes client secret rotation as a specific lifecycle where a new secret is added, the app is migrated, and the old secret is disabled: . RFC 6749 defines client id, client secret, and redirect uri as distinct OAuth parameters, and also notes that distributed clients can have components with different security contexts: . AWS Secrets Manager supports JSON key value secrets for coupled credential shapes, especially where rotation functions expect specific fields: . That validates the usefulness of structured credentials, but HASP should avoid copying the blob as authority model because HASP's local broker can preserve field level authorization. Kubernetes Secrets also allow multiple data keys in one Secret object: . That validates the operational need for multi key credentials, but Kubernetes' namespace and pod access model is not HASP's grant model. Required semantics A credential set must be value free in repo metadata. It can name member refs, roles, kinds, classification, and delivery recipes. It must never store member values in .hasp.manifest.json. Each member must retain its own: kind, such as kv or file classification, such as secret or public config vault item name named reference rotation state audit identity Set review must include: set name set kind and schema version member role to ref mapping member classifications target delivery mapping output paths for workspace visible materialization A grant to use a set must be scoped to a target/action. It must not imply plaintext reveal for every member. Doctor behavior hasp project doctor should validate a set as a unit while reporting member failures separately. Good diagnostics: missing client secret client id is present but not exposed to this project client secret is classified as public config, but the google oauth client schema requires secret target maps client secret to a workspace visible output without convenience approval target review is stale because the set member mapping changed Bad diagnostics: "group invalid" "item not found" "Google auth failed" Delivery behavior Credential sets should feed delivery recipes: env pair for frameworks that read GOOGLE CLIENT ID and GOOGLE CLIENT SECRET broker owned temp JSON file for libraries that require a client secrets file generated .env example with placeholders only workspace visible generated file only through explicit convenience approval Delivery recipes must be deny by default. A target that asks for client id does not receive client secret unless it maps that role explicitly. Open design work Before implementation, define: manifest schema field names and versioning built in schemas for google oauth client, database credentials, and service account JSON whether custom set kinds are allowed in v1 or only built in kinds review signature changes MCP listing and explain output for set backed targets migration path from today's explicit requirements and targets Rejected options Do not add a generic group item kind. It obscures sensitivity and makes the vault value shape do too much. Do not introduce tag based delivery for this. Tags are organization metadata, not an execution contract. Do not let repo manifests define arbitrary assembly scripts. Assembly must be a HASP owned recipe so values do not pass through shell expansion or agent visible text. Do not treat every member of a set as secret. Some members are config, and over classifying them creates unnecessary friction. Under classifying is worse, so each built in schema must declare the minimum safe classification per role. Interim v1 pattern Until credential sets ship, model coupled credentials with separate manifest requirements and explicit target delivery: This keeps the committed repo contract value free and preserves the main HASP invariant: values are brokered at execution time, not stored in source control or returned to agent context by default.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.31/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.31/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.31/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.31] Document the scoped credential set model for coupled credentials such as Google OAuth client IDs and client secrets, including the interim value free manifest pattern to use before credential sets ship. Restore and verify the source 100% coverage gate after the manifest target hardening work by adding focused coverage and removing unreachable branches. [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.31/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.31/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.31/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.31/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.31 (c972119c69) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.31/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.30/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.30/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.30/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.30/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.30/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.30/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.30/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.30/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.30/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.30/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.30/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.30/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, create a value free template with hasp template add env NAME=@NAME when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp targets, hasp target explain, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. When .hasp.manifest.json defines targets, call hasp targets first and prefer hasp run or hasp inject with target over raw broad mappings. If the repo has no manifest yet, ask the operator to create a value free template with hasp template add env NAME=@NAME or use the CLI yourself when local edits are allowed. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.30/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs hasp targets and hasp target explain can inspect value free manifest targets when .hasp.manifest.json is present One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer hasp run or hasp inject with a manifest target when the repo has .hasp.manifest.json; call hasp targets before raw mappings. If no manifest exists and local edits are allowed, use hasp template add env NAME=@NAME to create a value free template. Do not put raw values in .hasp.manifest.json. Before first use of a repo controlled target command, inspect with hasp run target explain dry run, then run hasp template review . Brokered target execution fails until the local review signature exists and is current. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.30/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.30] Add value free repo manifest target authoring and review commands through hasp project target ... and the hasp template ... alias, so agents can request brokered workflows without storing raw secret values in the repo. Require local target review before hasp run target, hasp inject target, hasp write env target, MCP target execution, or hasp app connect target can authorize refs or seed runtime profiles. Improve project binding diagnostics so hasp doctor, manifest backed secret flows, and hasp secret add expose distinguish unbound repos from bindings that point at missing vault items. [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.30/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.30/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.30/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.30/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.30 (3544119ed3) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp template hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.30/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.29/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.29/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.29/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.29/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.29/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.29/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.29/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.29/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.29/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.29/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.29/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.29/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi (Inflection AI)
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.29/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.29/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.29] Add hasp audit recover so operators can archive a degraded audit log, emit a recovery report, and start a fresh tamper evident chain without rewriting historical entries. Document the degraded audit log recovery workflow in the quickstart and generated CLI reference. [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.29/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.29/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.29/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.29/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.29 (8c375ae4b9) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit recover hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.29/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.28/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.28/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.28/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.28/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Enabling the trusted harness catalog is only the first gate. Destructive and binding mutations such as hasp secret expose, hasp secret hide, and hasp secret delete also require an explicit hasp session grant mutation for the named item and action. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.28/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.28/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.28/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.28/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference, alias, or safe named ref such as @OPENAI API KEY. Project binding alone does not expose existing vault items. hasp secret expose NAME project root updates binding metadata only; it does not reveal plaintext or write the secret into repo files. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Binding a repo does not expose any existing vault item by itself. Use hasp secret expose NAME project root when that repo needs an existing secret. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.28/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. expose existing vault items that repo needs with hasp secret expose NAME project root 4. use hasp run or hasp mcp 5. use hasp inject for broker owned file materialization outside the repo 6. use hasp write env only when the convenience tradeoff is worth it hasp project bind creates the repo boundary. It does not make every personal vault item visible to that repo. If an agent reports that @NAME exists but is not available in the project, expose that item explicitly. Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.28/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.28/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.28/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. Default MCP configs cannot auto expose secrets and do not include mutation tools. If a trusted local harness intentionally enables HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1, exposure/hide/delete still requires a matching hasp session grant mutation from the operator. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The default tool surface lists hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Default Codex CLI MCP cannot auto expose existing vault items. Ask the operator to run hasp secret expose NAME project root , or use a trusted local harness with unsafe tools enabled and hasp session grant mutation. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code's default MCP catalog lists hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. Trusted local harnesses may opt into hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret expose, and hasp secret hide, but those mutation tools are not part of the default catalog. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Default Claude Code MCP cannot auto expose existing personal vault secrets. Ask the operator to run hasp secret expose NAME project root . Use MCP mutation tools only in a trusted local harness after setting HASP MCP ENABLE UNSAFE SECRET WRITE TOOLS=1 and granting the matching hasp session grant mutation. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp secret get, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.28/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Default MCP configs cannot auto expose existing vault items. If an agent finds that @NAME exists but is not available in the project, an operator should run hasp secret expose NAME project root . Trusted local harnesses that enable unsafe mutation tools still need hasp session grant mutation before expose, hide, or delete can succeed. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.28/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.28] Distinguish missing named references from existing vault items that are not exposed to the current project, with specific CLI and MCP recovery metadata. Keep default MCP secret tooling safe by default while documenting the explicit operator path for exposing existing vault items to a repo. Add release blocking web dependency audit coverage and patch the vulnerable ws transitives in the private docs toolchain. Rotate download Worker release pins through secrets by default, avoiding route aware Worker deploys unless explicitly requested. [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.28/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.28/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.28/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.28/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.28 (1be2d32b7f) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.28/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root ; binding the repo alone is not enough if the secret truly does not exist, create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root expose an existing vault item explicitly with hasp secret expose project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose an existing vault item to the repo with hasp secret expose project root ; hasp project bind alone does not expose existing vault items if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.27/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.27/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.27/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.27/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.27/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.27/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.27/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.27/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.27/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.27/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.27/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.27/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.27/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.27/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.27] Accept trailing known flags across the remaining hasp secret subcommands, including hasp secret add NAME from stdin expose=never json. Track the next surgical release hardening work for vulnerable web toolchain transitives, package manager audit gates, and Node deprecation warnings. [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.27/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.27/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.27/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.27/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.27 (ece9aacd33) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.27/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.26/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.26/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.26/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.26/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.26/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.26/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.26/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.26/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.26/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.26/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.26/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.26/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.26/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.26/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.26] Prevent hasp secret expose NAME project root json from partially succeeding and then returning a false E NOT FOUND by parsing trailing command flags before secret name mutation. Add regression coverage for agent style secret exposure commands where flags follow the named secret. Track the next surgical hardening work for secret command flag parsing, unexposed named reference diagnostics, and MCP project exposure metadata. [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.26/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.26/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.26/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.26/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.26 (02cb57fb5f) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.26/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.25/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.25/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.25/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.25/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.25/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.25/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.25/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.25/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.25/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.25/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.25/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.25/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.25/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.25/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.25] Restore brokered Claude Code and Codex CLI secret delivery for ad hoc macOS CLI installs by falling back to the local daemon HMAC file when the running binary does not match app bundle signing requirements. Prevent future audit sequence collisions by serializing audit appends across independent CLI and MCP processes. Keep MCP sessions project bound for existing rootless agent records by resolving the repo from HASP AGENT PROJECT ROOT or the agent process working directory. [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.25/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.25/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.25/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.25/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.25 (9ec99f581e) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.25/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.24/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.24/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.24/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.24/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.24/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.24/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.24/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.24/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.24/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.24/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.24/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.24/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.24/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.24/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.24] Use the release build bootstrap profile for the macOS public artifact build job so release publication does not depend on Linux verification tooling. [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.24/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.24/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.24/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.24/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.24 (c71784da5c) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.24/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.23/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.23/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.23/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.23/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.23/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.23/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.23/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.23/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.23/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.23/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.23/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.23/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.23/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.23/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.23] Repair the public release workflow for Darwin native daemon HMAC keychain artifacts by building the full public release set on macOS. Keep Linux public preflight focused on static package contract checks when Darwin CGO artifacts cannot be built on that runner. [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.23/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.23/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.23/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.23/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.23 (37761723e3) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.23/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.22/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.22/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.22/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.22/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.22/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.22/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.22/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.22/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.22/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.22/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.22/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.22/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.22/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.22/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.22] Make Claude Code and Codex CLI MCP startup survive slow daemon initialization by waiting for readiness before the agent MCP handshake proceeds. Add a release blocking MCP gate that verifies bare MCP startup, Claude/Codex managed wrappers, generated MCP config, and tool listing before release artifacts can ship. Block Darwin release artifacts that contain stubbed daemon HMAC keychain support, preventing packages built with test fast KDF/no cgo paths from breaking brokered secret delivery. [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.22/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.22/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.22/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.22/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.22 (1703995797) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.22/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.21/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.21/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.21/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.21/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.21/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.21/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.21/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.21/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.21/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.21/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.21/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.21/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.21/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.21/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.21] Add Pi as a first class brokered agent profile with setup support, generated local package bridging, profile metadata, docs, release gates, and public mirror coverage. Restore basic terminal interrupt behavior during interactive hasp setup so the first Ctrl C terminates setup instead of being swallowed by context cancellation. Harden release verification around stale download Worker metadata so live release checks report the pinned Worker version precisely. [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.21/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.21/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.21/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.21/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.21 (e29506bacc) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.21/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.20/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the seven first class profiles (Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for pi it registers a generated package in Pi settings; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.20/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.20/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.20/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Pi, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.20/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.20/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.20/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.20/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.20/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.20/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.20/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.20/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI Pi OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / Pi
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/pi/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/pi.md
--------------------------------------------------------------------------------

Pi Config Surface Prefer hasp setup agent pi or hasp agent connect pi; HASP writes a generated Pi package under HASP HOME/pi package and registers that package path in Pi's settings.json. Canonical broker command behind the generated extension: hasp agent mcp pi Pi's config directory follows PI CODING AGENT DIR when that environment variable is set, otherwise it defaults to /.pi/agent. Config Example The package contains an extension that discovers HASP MCP tools from the managed wrapper and registers them as Pi tools. Setup 1. Bootstrap the local profile: hasp bootstrap profile pi project root alias secret 01= 2. Connect Pi: hasp agent connect pi project root 3. Verify Pi sees the package: pi list 4. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp pi Bootstrap may create a neutral repo alias such as secret 01, but day to day Pi usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior The generated Pi extension starts the managed wrapper, which invokes hasp agent mcp pi and opens a daemon backed session for the bound project when no explicit session token is supplied. Use broker side project and secret window grants for longer Pi sessions instead of repeated manual approvals. If PI CODING AGENT DIR points at an alternate Pi config directory, HASP installs the package reference there. Success Signal pi list includes the generated HASP HOME/pi package package path. Pi lists brokered HASP tools such as hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when Pi needs a broker owned file path outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Pi setups enable HASP agent safe mode through the managed wrapper, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the brokered no plaintext in agent context path. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery Rerun hasp agent connect pi project root if the generated package path is missing from pi list. If the generated extension reports hasp status instead of normal tools, verify the managed wrapper exists under HASP HOME/bin/hasp agent pi and that hasp agent mcp pi can list tools from the same working tree. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats Pi uses a package/extension surface rather than a native MCP config file, so HASP registers a generated local package instead of writing an mcpServers block. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.20/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.20/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.20] Restore and verify the server 100% coverage gate across app setup, MCP authorization, broker operations, project context, HTTP helpers, runtime process identity, store grants, and telemetry payload tooling. Keep the exported public mirror aligned with the private source coverage suite, including the new coverage focused regression tests. Fix a runtime backup scheduler race test hazard by making test scheduler timing instance local instead of mutating shared package state. [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.20/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.20/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.20/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.20/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.20 (b79a86eb45) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.20/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.19/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.19/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.19/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.19/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.19/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.19/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.19/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.19/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.19/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.19/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.19/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.19/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.19/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.19/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.19] Close the May 16 security review backlog with broker authorization hardening, public Worker ingress controls, dependency and OSV gates, static docs XSS containment, public recon drift tracking, and release verification coverage. Add structured authorization requirements for broker grant actions and share brokered run/inject execution across CLI and MCP while keeping write env as a separate workspace visible export path. Harden macOS HTTP signing to fail closed on randomness failures and extend the signer contract tests. [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.19/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.19/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.19/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.19/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.19 (90ae6bd450) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.19/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.18/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.18/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.18/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.18/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.18/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.18/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.18/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.18/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.18/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.18/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.18/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.18/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.18/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.18/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.18] Make public release gates prove the live first party telemetry endpoint by generating the probe body from the core CLI telemetry encoder, then checking DNS, TLS SNI, and the /v1/cli/ping response contract before release. [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.18/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.18/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.18/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.18/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.18 (9694982650) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.18/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.17/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.17/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.17/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.17/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.17/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.17/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.17/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.17/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.17/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.17/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.17/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.17/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.17/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.17/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.17] Ship the process identity authorization hardening with deterministic Darwin race test coverage after the v1.0.16 public release workflow stopped before publishing artifacts. [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.17/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.17/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.17/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.17/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.17 (34cc36119c) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.17/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.16/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.16/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.16/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.16/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.16/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.16/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.16/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.16/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.16/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.16/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.16/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.16/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.16/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.16/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.16] Harden process bound session resolution so daemon RPC callers can only resolve sessions for their kernel attested socket peer PID. Disable implicit process binding when the platform cannot provide a per process stale binding token instead of falling back to PID ancestry. Replace shell based process ancestry checks with native platform lookups and refuse daemon stop when a pidfile does not match the live HASP daemon socket. [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.16/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.16/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.16/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.16/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.16 (bd48bdaa09) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.16/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.15/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.15/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.15/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.15/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.15/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.15/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.15/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.15/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.15/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.15/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.15/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.15/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.15/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.15/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.15] Harden the public release workflow against transient macOS arm64 race test runner failures by retrying the Darwin race step once before failing. [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.15/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.15/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.15/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.15/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.15 (d6ea45859e) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.15/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.14/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.14/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.14/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.14/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.14/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.14/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.14/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.14/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.14/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.14/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.14/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.14/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.14/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.14/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.14] Make the setup convenience unlock eval platform aware so Linux CI verifies the disabled path while macOS verifies best effort Keychain unavailability. [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.14/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.14/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.14/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.14/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.14 (976c762b87) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.14/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.13/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.13/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.13/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.13/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.13/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.13/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.13/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.13/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.13/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.13/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.13/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.13/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.13/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.13/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.13] Keep public release evals aligned with the setup convenience unlock hardening so merge gate CI covers the new macOS Keychain failure contract. [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.13/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.13/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.13/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.13/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.13 (843e91b077) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.13/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.12/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.12/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.12/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.12/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.12/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.12/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.12/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.12/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.12/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.12/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.12/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.12/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.12/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.12/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.12] Make setup keychain failures explicit: convenience unlock errors now say the macOS login keychain rejected access, not the HASP master password. Show Setup complete with warnings when setup succeeds but convenience unlock is unavailable. Treat enable convenience unlock=always as a hard setup contract so setup cannot report success while leaving the requested unlock path unusable. [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.12/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.12/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.12/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.12/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.12 (e0bba966b6) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.12/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.11/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.11/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.11/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.11/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.11/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.11/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.11/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.11/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.11/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.11/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.11/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.11/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.11/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.11/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.11] Made the public installer regression test portable to clean Linux runners by accepting the expected "install directory is not on PATH" warning while preserving the dedicated stale hasp shadowing assertion. Continue the 100% server coverage release line after the v1.0.10 public CI attempt exposed the Linux only installer test assumption. [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.11/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.11/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.11/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.11/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.11 (93330d4b6f) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.11/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.10/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.10/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.10/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.10/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.10/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.10/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.10/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.10/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.10/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.10/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.10/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.10/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.10/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.10/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.10] Split public script test execution into named release and merge gate steps so Linux CI identifies the exact script regression instead of reporting the aggregate test scripts lane. Continue the 100% server coverage release line with a small release version parser regression test. [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.10/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.10/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.10/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.10/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.10 (3bbb1c958f) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.10/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.9/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.9/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.9/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.9/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.9/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.9/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.9/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.9/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.9/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.9/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.9/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.9/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.9/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.9/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.9] Split the public verify ci aggregate into named workflow steps for release and merge gates so Linux CI reports whether links, generated docs, workflow lint, shellcheck, web checks, server tests, or server lint failed. Carry forward the 100% server coverage gate and release diagnostic hardening from the v1.0.7 and v1.0.8 release attempts. [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.9/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.9/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.9/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.9/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.9 (c273d4f3f6) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.9/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.8/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.8/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.8/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.8/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.8/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.8/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.8/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.8/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.8/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.8/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.8/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.8/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.8/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.8/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.8] Move public non secret release preflight and merge gate checks to GitHub hosted Linux and split the release gates into named steps so CI failures identify the exact failing lane instead of collapsing into one opaque make release gate or make release preflight result. Preserve the 100% server coverage release gate and the v1.0.7 MCP/coverage hardening in the release line. [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.8/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.8/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.8/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.8/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.8 (9a1b5fd7f8) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.8/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.7/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.7/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.7/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.7/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.7/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.7/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.7/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.7/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.7/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.7/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.7/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.7/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.7/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.7/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.7] Raise the server release coverage gate to 100% with regression coverage across runtime HTTP/RPC paths, app command errors, HTTP auth/HMAC handling, integrations, store backup/config/policy paths, telemetry, leases, approvals, and support utilities. Simplify unreachable defensive branches surfaced by the coverage push while preserving production error handling for reachable failure modes. [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.7/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.7/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.7/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.7/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.7 (5ea421c8e7) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.7/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.6/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.6/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.6/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.6/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.6/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.6/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. If hasp version still prints an older version after Homebrew upgrades, another install is earlier on your shell's PATH. Run: Remove the older binary, or move Homebrew's bin directory earlier in PATH, then run hash r in open shells before checking hasp version again. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.6/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.6/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.6/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.6/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.6/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.6/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.6/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.6/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.6] Harden managed agent MCP startup so initialization and tool discovery stay available even when vault unlock, saved consumer lookup, session setup, or process registration preflight fails. Contain vault unlock failures during MCP tool execution as JSON RPC tool errors instead of process exits. Isolate HTTP vault init regression coverage from the operator macOS Keychain. [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.6/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.6/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.6/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.6/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.6 (c84c126a5a) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.6/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.5/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use keeps telemetry disabled unless you explicitly opt in HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. telemetry.md covers opt in CLI telemetry, payloads, retention, erasure, and the hard runtime kill switch. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.5/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.5/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.5/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.5/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.5/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.5/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.5/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.5/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE HASP TELEMETRY DISABLED HASP TELEMETRY DISABLED=1 is a hard runtime kill switch for optional CLI telemetry. It prevents enabling telemetry and prevents all telemetry sends even when prior consent exists. Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Telemetry
URL: https://gethasp.com/docs/v1.0.5/telemetry/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/telemetry.md
--------------------------------------------------------------------------------

Telemetry HASP CLI telemetry is disabled by default. The CLI never sends telemetry unless you explicitly opt in during hasp setup or by running hasp telemetry enable. The hard runtime override is: When this variable is set, telemetry cannot be enabled and no telemetry network request is made even if prior consent was saved. Destination Opted in CLI telemetry goes only to HASP's first party endpoint: The CLI does not send telemetry directly to PostHog, Umami, Segment, or any other third party analytics endpoint. Commands status shows consent state, environment override, endpoint, schema version, last ping time, and a short install hash prefix. enable shows the policy summary and asks for confirmation unless yes is provided. disable withdraws consent and stops collection and sending. forget deletes local telemetry state and requests erasure for retained install hashes when the endpoint is configured. preview prints the exact payload builder output without sending it. These commands do not require the daemon, vault unlock, or a broker session. Setup Consent Interactive hasp setup asks whether to allow optional CLI telemetry. The default answer is no. Non interactive setup uses an explicit flag: yes never implies telemetry consent. Payload Contract Telemetry uses one daily aggregate payload with schema version 1. Allowed fields: schema version install id hash hasp version os arch install method period hours commands 24h commands total top root commands setup features safety errors performance Allowed counters are fixed to public command or feature names. Unknown fields are rejected by the client encoder and by the first party ingest service. Data HASP Never Sends HASP telemetry must never include: secret values secret names aliases refs vault IDs session tokens project paths repo names file names environment variable names command arguments or full command lines hostnames usernames or local user IDs raw error strings stack traces stdout or stderr audit log entries The local audit log remains local. Telemetry is not an audit log export path. Local State Telemetry consent and counters are stored outside the encrypted vault so that hasp telemetry disable and hasp telemetry forget work while the vault is locked. The state file is written under the user's config directory with 0600 permissions where the platform supports POSIX modes. The local install identity is random and rotates yearly. HASP sends only a derived hash. Prior hashes are retained locally long enough for forget to request erasure for rows that may still be inside the server retention window. Retention And Erasure The source of record is a first party Cloudflare Worker backed by Cloudflare D1. Live rows are keyed by install hash and day so they can be deleted when hasp telemetry forget sends an erasure request. The erasure ledger stores only install hash, timestamp, source, status, and deleted row count. It is retained only for accountability. D1 Time Travel and backups can retain deleted rows until the configured backup window expires. Restore runbooks must not reintroduce erased rows without replaying the erasure ledger. Downstream Analytics The default analytics path is D1 only. If HASP later mirrors aggregate telemetry to another analytics tool, the mirror must run server side after validation and redaction. The CLI network contract remains first party only. Downstream mirrors must not use session replay, autocapture, surveys, feature flags, user profiles, or raw install identity. Contributor Rules New telemetry fields require all of the following in the same change: this document updated allowlist/schema update in the client and ingest service tests proving the field cannot carry forbidden data privacy review notes release note disclosure If any of those pieces are missing, the field must not ship.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.5/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.5/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.5/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.5/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.5] Add optional HASP CLI telemetry with explicit setup consent, hasp telemetry controls, a first party ingest endpoint, strict payload allowlists, and default off/no network behavior unless the user opts in. [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.5/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.5/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set, uses https://downloads.gethasp.com/hasp/releases/ /. Documentation release gate Do not cut a tag until the docs match the release. Before creating a tag: 1. Update every public doc page affected by new or exposed functionality. 2. Update examples, command output, install steps, agent profile pages, and error guidance when behavior changes. 3. Add any new docs page to the docs index/navigation source. 4. Do not publish a new docs version yet; versioned public docs are created only after the core HASP app release tag exists. 5. Keep the release gate process bounded: the Go test wrapper defaults package parallelism to p 1, and daemon lifecycle changes should leave no app.test daemon serve, runtime.test daemon serve, or hasp evals bin /hasp daemon serve helpers behind. The public /docs/ route and every release route /docs/vX.Y.Z/ must describe a currently released core HASP app tag. Do not use the macOS wrapper roadmap or an unreleased VERSION bump to create a public docs version. Source build The local binary lands at bin/hasp. Direct packaged release Lifecycle helpers: Release trust path verify the signed checksum manifest verify the tarball signature verify the packaged binary signature install only the exact release bytes that were published


================================================================================
Reference / Glossary
URL: https://gethasp.com/docs/v1.0.5/glossary/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/glossary.md
--------------------------------------------------------------------------------

Glossary HASP uses a small vocabulary. These terms show up in help output, docs, audit events, and errors. Vault The encrypted local store under HASP HOME. The vault stores named items on the machine. It proves that the secret exists locally. It does not decide which repo, app, agent, or command may receive the value. Item One named secret in the vault. An item can be a token, password, connection string, or file shaped credential such as a JSON service account. Reference A name or alias a repo can request. The reference can be safer to show than the raw vault item name. A repo can ask for secret 01 while the vault item keeps its provider specific name. Project The repo root HASP uses as a boundary. Commands running inside that boundary can use the references exposed to that project. Another repo does not inherit those references just because it runs on the same machine. Binding The record that connects a project to visible references. If a brokered command cannot see a secret, inspect the binding before copying plaintext into the repo. Target A named workflow inside a project. Targets are declared in .hasp.manifest.json. A target can describe the refs, delivery names, root, command argv, and placeholder examples for one workflow. It is repo metadata, not authorization. See Value free manifests for the manifest contract. Consumer An app, agent, command, or MCP client that asks HASP for access. Apps usually need environment variables or files. Agents should prefer references and brokered tools so the raw value stays out of prompts, logs, and generated files. Grant Scoped permission to deliver a value. A grant matches actor, project, action, and time scope. The vault holding a value is not enough for delivery. Session Broker context for a running consumer. Sessions let HASP track which host, process, repo, and temporary plaintext exceptions belong to a request. MCP The tool protocol agents use to talk to HASP without reading raw values. Use MCP when an agent can work through brokered tools. Use hasp run or hasp inject when a normal command needs environment variables or files. Audit log Local evidence for operations and access, written as a chain. Audit helps you understand what happened. It does not make a leaked secret safe after the fact. Plaintext grant A short exception that allows a protected reveal or copy action. Use it for manual work only. Keep the scope short and rotate the upstream value if it lands in an unsafe place.


================================================================================
Reference / CLI reference
URL: https://gethasp.com/docs/v1.0.5/cli-reference/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md
--------------------------------------------------------------------------------

HASP CLI reference Build: 1.0.5 (0a97ce3f39) Generated by hasp docs markdown. Every help topic is rendered verbatim inside a fenced code block so leading whitespace and table characters survive the markdown round trip. Root help hasp init hasp setup hasp bootstrap hasp doctor hasp import hasp set hasp capture hasp secret hasp secret add hasp secret update hasp secret rotate hasp secret delete hasp secret get hasp secret retrieve hasp secret show hasp secret reveal hasp secret copy hasp secret list hasp secret diff hasp secret expose hasp secret hide hasp app hasp app connect hasp app run hasp app install hasp app shell hasp app disconnect hasp app list hasp agent hasp agent connect hasp agent mcp hasp agent launch hasp agent shell hasp agent disconnect hasp agent list hasp agent list supported hasp project hasp run hasp inject hasp write env hasp check repo hasp proof hasp daemon hasp session hasp session grant plaintext hasp session grant mutation hasp lease hasp lease list hasp lease revoke hasp approval hasp approval list hasp approval decide hasp access hasp access matrix hasp policy hasp policy show hasp policy set hasp policy validate hasp config hasp config show hasp config get hasp config set hasp telemetry hasp vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit export hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes


================================================================================
Reference / Errors
URL: https://gethasp.com/docs/v1.0.5/error-codes/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/error-codes.md
--------------------------------------------------------------------------------

Reading HASP error messages HASP errors have two stable layers: an exit bucket from 0 through 6 an error code such as E NOT FOUND when the command runs with json Use the code when you need precise automation. Use the exit bucket when a script only needs to know the broad class of failure. The error envelope Plain commands print a human message on stderr: JSON commands print one machine readable error envelope on stderr: Shape: Fields: code: stable machine readable error code message: human readable context for this exact failure hint: optional next action when HASP can give one safely Read an error in this order: 1. code 2. exit bucket 3. hint 4. message Do not parse the English message in scripts. It is allowed to get clearer over time. Exit buckets Exit Bucket Codes 0 ok command succeeded 1 generic / internal E INTERNAL or an uncategorized failure 2 user input E USER INPUT, E NOT IN REPO 3 permission E PERMISSION, E GRANT DENIED, E VAULT LOCKED, E PASSWORD WRONG 4 daemon / I/O E DAEMON UNREACHABLE 5 leak detected E REPO LEAK 6 not found E NOT FOUND Error codes E INTERNAL Exit bucket: 1. HASP could not classify the failure more specifically. This is the fallback for unexpected runtime failures and plain Go errors that do not match a known category. Common triggers: an unexpected local runtime failure a current user lookup failure during runtime setup an error path that has not yet been wrapped with a more specific HASP code What to do: run the smallest command that reproduces the failure run hasp doctor include hasp version, the command, and the JSON error envelope when filing a bug E USER INPUT Exit bucket: 2. The command shape is wrong or HASP needs different input before it can safely continue. Common triggers: unknown command unsupported flag missing required argument or flag invalid flag value malformed command grammar a refusal to overwrite an existing file a broker reference that is not exposed to the current repo What to do: run hasp help for the command you were trying to use check spelling, flags, and required values if the hint says a reference is not exposed, run hasp secret expose project root . or create it with hasp secret add prefer hasp setup when you are trying to do first run configuration E NOT IN REPO Exit bucket: 2. The command needs repository context and HASP could not determine one. Common triggers: running a repo scoped command outside a git checkout omitting project root for a command that needs a project using a path that no longer points at the intended repo What to do: cd into the repo and retry pass project root /path/to/repo run hasp setup or hasp project bind project root /path/to/repo Some older or generic paths may classify the text "not in a git repository" as E USER INPUT. Treat both codes as exit bucket 2 and fix the repo context. E PERMISSION Exit bucket: 3. HASP refused access for a permission reason, but the failure was not specific enough to use E GRANT DENIED, E VAULT LOCKED, or E PASSWORD WRONG. Common triggers: a permission check fails before a more specific category is available a future broker or platform permission path reports a generic denial What to do: read the hint when one is present verify the vault is unlocked verify the project is bound retry with an explicit grant scope only when the action is intentional E GRANT DENIED Exit bucket: 3. HASP found the requested project or secret path, but the current session does not have the grant needed to deliver the value. Common triggers: a project lease is required for hasp run or hasp inject a secret grant is missing, expired, or denied a repo has not been bound before a brokered operation What to do: run hasp setup inside the repo for the guided path bind explicitly with hasp project bind project root grant explicitly with hasp session grant project for command delivery, pass intentional grant flags such as grant project window and grant secret session E VAULT LOCKED Exit bucket: 3. HASP could not open the encrypted local vault. Common triggers: first run has not initialized the vault HASP MASTER PASSWORD is not set in a non interactive shell the process cannot prompt for the master password What to do: run hasp setup for scripted use, set HASP MASTER PASSWORD if you are building the vault manually, run hasp init When this code is produced from the vault not initialized path, the hint is: E PASSWORD WRONG Exit bucket: 3. The password was present, but it did not unlock the vault. Common triggers: typo in an interactive password prompt stale HASP MASTER PASSWORD in the shell using a password from a different local vault or restored backup What to do: retry with the correct local master password clear or replace HASP MASTER PASSWORD if the shell value is stale if the vault was replaced, restore the matching backup or initialize a new vault intentionally E DAEMON UNREACHABLE Exit bucket: 4. HASP expected to reach the local daemon or broker path and could not. Common triggers: the daemon is not running a local socket is stale a connection is refused a daemon request times out or reports unreachable What to do: run hasp doctor restart the daemon or the app that owns the broker connection retry the command after the local runtime is healthy The generic classifier maps daemon messages containing phrases such as not reachable, unreachable, connection refused, or dial unix to this code. E REPO LEAK Exit bucket: 5. hasp check repo found managed secret values in repository files. Common triggers: a real secret was written into .env, .env.local, logs, fixtures, or generated output a previous manual copy or reveal left plaintext in the working tree a support bundle or release artifact includes a managed value What to do: remove the plaintext from the repo file rotate the secret if it was committed, shared, or uploaded rerun hasp check repo project root . use allow managed secrets only when the override is intentional and reviewed When this code blocks a repo scan, the hint is: E NOT FOUND Exit bucket: 6. The named object is not in the vault or local HASP metadata. Common triggers: secret name does not exist binding, grant, or reference was removed a script uses a name from another machine, backup, or repo a repo visible reference points at a missing vault item What to do: run hasp secret list check the exact name and case create the secret with hasp secret add expose it to the repo with hasp secret expose project root . if this started after cleanup, update scripts to use a current reference Script examples Branch on the exit bucket when that is enough: Branch on the structured code when you need precision:


================================================================================
Start / Overview
URL: https://gethasp.com/docs/v1.0.4/overview/
Source: https://github.com/gethasp/hasp/blob/main/public/README.md
--------------------------------------------------------------------------------

HASP HASP is a local secret broker for coding agents. Agents need credentials to run tests, call APIs, and deploy code. Copying those credentials into prompts, shell history, .env files, or repo local notes makes the agent faster today and harder to trust tomorrow. HASP keeps secrets in a local encrypted vault and gives commands only the values they are allowed to use at runtime. The core rule is: Managed secret values must not enter agent context. Install Use Homebrew for normal installs on macOS and Linux: Then run the guided setup: For source builds: See install.md for packaged release verification, upgrades, and uninstall steps. hasp upgrade version vX.Y.Z fetches and verifies a signed release in place; run hasp help upgrade for flags and trust roots. First proof Add a secret, connect a project, and run a command through the broker: For the full first run path, start with QUICKSTART.md. For the operating model behind vaults, grants, bindings, and agent profiles, read mental model.md. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports run, inject, MCP, and app connection flows materializes plaintext only when an operator asks for that tradeoff installs repo hooks that block managed secrets from commits and deploy paths keeps audit records for brokered secret use HASP is local first. It does not require a hosted control plane for v1. Repo layout The Go code lives in apps/server because the released module path is github.com/gethasp/hasp/apps/server. Keeping that path stable avoids breaking imports, release scripts, Homebrew packaging, and downstream source builds. Development Use the root Makefile for normal local work: The server module has the same focused targets under apps/server: Script details are in scripts/README.md. Server internals are in apps/server/README.md. Docs install.md covers Homebrew and packaged releases. after homebrew.md covers first setup after install. command guide.md maps jobs to commands. cli reference.md lists generated command help. operator guide.md covers day to day operations. value free manifests.md explains safe manifests. agent profiles cover the six first class profiles (Codex CLI, Claude Code, Cursor, Aider, Hermes, OpenClaw) and the generic broker path. hasp agent connect writes the MCP config in place for claude code, codex cli, and cursor; for aider, hermes, and openclaw it installs the wrapper at $HASP HOME/bin/hasp agent and you wire it into the agent per the matching profile doc. The full docs index is docs/README.md. Security Report security issues through SECURITY.md. Please do not open a public issue for a suspected vulnerability. License HASP is source available under the Fair Core License. See LICENSE.


================================================================================
Start / Quickstart
URL: https://gethasp.com/docs/v1.0.4/quickstart/
Source: https://github.com/gethasp/hasp/blob/main/public/QUICKSTART.md
--------------------------------------------------------------------------------

Quickstart This file covers the shortest safe path to a working local HASP install. If you already installed HASP and want the full beginner flow, read After Install. For the simplest first run path, use: Interactive setup can now stop after machine setup, skip agent setup, or continue directly into adding a secret and connecting one app. To learn the CLI directly from the binary, use: The manual steps below remain the fallback path and the troubleshooting reference. Current UX The current build supports both the lower level broker commands and the newer consumer commands: hasp secret add hasp app connect hasp app run hasp app install hasp agent connect Use the consumer commands for normal vault, app, and agent setup. Keep hasp run, hasp inject, and hasp write env for advanced brokered flows. 1. Build or download a release From source: From a packaged release: The packaged verifier expects these sidecars next to the tarball: SHA256SUMS SHA256SUMS.asc hasp release public key.asc .tar.gz.asc bin.asc 2. Initialize the local vault 3. Import a secret file Or add one directly without creating a temp file: 4. Bind a repo and install guardrails If you are already inside the repo and just want to save a secret and use it there, the human first path is now: If you already enabled automatic repo adoption and want to enroll several local git repos at once, use: That scans for git backed project roots, skips non project directories, and binds the matching repos using the machine defaults from hasp setup. 5. Use the brokered path 6. Upgrade or uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless you pass explicit cleanup flags. Known limits of v1 V1 is local first. There is no hosted control plane. V1 reduces accidental exposure on a normal developer machine. It does not provide strong same user local isolation. HASP does not manage your PATH by default. App launchers and PATH edits require explicit consent. Pasted values and shell exports become managed only after you import or capture them. hasp write env, hasp secret reveal, and hasp secret copy put plaintext back in human visible places. Use them when that tradeoff is intentional. Where to go next Read the mental model to understand vaults, bindings, grants, and brokered delivery. Use the command guide when you know the job but not the command. Keep the glossary nearby when command output uses a term you do not recognize.


================================================================================
Start / Mental model
URL: https://gethasp.com/docs/v1.0.4/mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/mental-model.md
--------------------------------------------------------------------------------

Mental model HASP gives you a way to stop handing secrets to tools as plain text. Think in six objects: a vault stores named secrets on your machine a project binding says which repo can use which names a target says which workflow receives which subset a consumer is an app or agent that wants access a grant allows one scoped delivery the broker does the delivery and writes the audit trail That is the product. The rest of the CLI exists to create, inspect, and repair those objects. Use the Glossary when you need the exact vocabulary. The short version You put secrets into the vault. You bind a repo. A committed value free manifest can describe requirements and targets. You connect the app or agent that works inside that repo. HASP gives the app or agent a reference, then resolves that reference at execution time. The app gets the value. The agent should get metadata, handles, or brokered tools. The repo gets guardrails. The audit log records the action. This is the shape to keep in your head: mental model Vault Stores the named item on this machine. → Project Checks the repo boundary and visible reference. → Grant Matches actor, action, scope, and time. → Broker Delivers to the app, agent, or command and writes audit. Read the checks in order. The value starts in the vault. The project binding says whether this repo can name it. The grant says whether this request can receive it. The broker delivers only after those checks pass. You can use HASP for normal local commands too. The agent safe path matters because coding agents read their own prompts, logs, command output, and sometimes the files they just wrote. A value that appears in any of those places can become part of the agent context. HASP tries to keep the value out of that context. The vault The vault is the local encrypted store under HASP HOME. It holds named items such as OPENAI API KEY, DATABASE URL, or a JSON service account. The vault answers one question: do I have this secret on this machine? Vault answers Do I have this secret here? It stores named items under HASP HOME . It does not choose the repo, actor, action, or time window. Policy answers Which repo? Which ref? Which actor? How long? Opening the vault proves possession. Bindings, sessions, and grants decide use. The vault does not answer: which repo may use it which agent may ask for it whether this command should receive it right now whether plaintext display is allowed Those decisions live in bindings, sessions, and grants. Use hasp init when you want the vault and nothing else. Use hasp setup when you want the guided path that can create the vault, bind a repo, import values, and connect a consumer. Vault items and references A vault item is the stored secret. A reference is the name or alias a command can ask for. Those two things are related, but they are not the same. OPENAI API KEY might be the item in the vault. A repo can expose it as secret 01 or STRIPE TEST KEY. The alias lets you give a project a stable handle without teaching every tool the real vault name. That distinction matters in docs, logs, and agent prompts. The handle can appear in those places. The value should not. Use hasp secret list to see managed items and visible references. Use hasp secret show or hasp secret get to inspect metadata. Use hasp secret reveal or hasp secret copy when you need plaintext and you are outside a protected agent flow, or after you issue a short plaintext grant. The project binding A project binding is a repo boundary. It tells HASP that commands running inside a project can request a named set of secrets. The binding answers two questions: which repo is asking which vault items that repo can name HASP treats project roots as explicit boundaries. That keeps a value you imported for one repo from leaking into another repo because both happen to run on the same machine. Use hasp project bind when you want a direct binding. Use hasp bootstrap when you want a repo binding plus an agent profile. Use hasp project adopt when you want HASP to scan a workspace and bind many git repos with the same defaults. Targets A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. Targets live in .hasp.manifest.json and are value free. They say which refs a workflow needs and how those refs should be delivered. They do not approve access, store values, or make the whole project secret set available. Read Value free manifests for the full contract. Use hasp project requirements and hasp project targets to inspect the repo contract. Use hasp run target , hasp inject target , or hasp write env target when you want HASP to expand one declared subset through the normal broker path. Consumers A consumer is anything that asks HASP for a secret. HASP has two consumer families: apps, which you run through hasp app agents, which you connect through hasp agent or hasp mcp Apps tend to expect environment variables or files. Agents need more care. They can inspect output, write files, run shell commands, and call tools. HASP gives agents a brokered surface so they can request a managed value without reading the raw value. Use hasp app connect for a local app profile. Use hasp agent connect for a coding agent profile. Use hasp mcp or hasp agent mcp when an agent speaks MCP over stdio. Grants A grant is permission to resolve a reference. It is valid only when the actor, project, action, and time scope all match. grant scope Actor Which app, agent, command, or MCP client is asking? Project Which repo root is this request attached to? Action Resolve, reveal, copy, run, inject, or write? Time Once, the current session, or a short window? All four must match. A value existing in the vault is not enough for delivery. A grant stays small: one actor, one project, one action, one short scope. Grants prevent the vault from becoming a global local dictionary. A command should not get a value because the value exists. It should get the value because the current project, consumer, and action match a scoped grant. HASP uses short scopes: once for one delivery session for the current broker session window for a short time window Use once for one off commands. Use session when a tool needs a few related requests. Use window when a local workflow would become noisy with repeated prompts, and keep the window short. Sessions A session is the broker side context for a consumer. It lets HASP answer questions such as: which host or agent is asking which project root the request belongs to whether the request is still alive whether plaintext display has a temporary exception Most users should not need to manage sessions by hand. hasp run, hasp inject, hasp app, and hasp agent open and use sessions for their flows. Use hasp session open when you need to debug a brokered flow. Use hasp session resolve to inspect a token. Use hasp session revoke when you want to shut down one token or all active sessions. Use hasp session grant plaintext when an operator has to allow a protected reveal or copy action for a short window. Brokered execution Brokered execution means HASP resolves values at the last moment and gives them to the child process, not to the repo and not to the agent transcript. hasp run resolves environment references: hasp inject resolves environment values and file references: hasp write env writes a repo visible env file on purpose. Treat it as a convenience tool, not the default safe path. The MCP path MCP changes the trust boundary. A shell command receives environment variables. An MCP client receives tools. When an agent connects to hasp mcp, the agent can call HASP tools instead of reading a raw .env file. The value stays behind the broker. The agent gets the result it needs, or a refusal that explains which grant, project, or reference is missing. Use MCP when the agent can work through tools. Use hasp run when you need to run a normal command. Use hasp inject when the command needs a temp credential file. Audit The audit log gives you local evidence. It records setup, bindings, grants, secret operations, app and agent connections, brokered deliveries, and failures. The audit log does not make a secret safe after it leaks. It gives you the trail you need to see what happened and what to rotate. Use hasp audit for a full local log. Use hasp audit tail when you want recent events during setup or debugging. Use hasp audit incident bundle when you need a redacted package for review. Redaction Redaction is a backup guard, not the main design. The safer design is to keep secrets out of output. Redaction helps when a managed value shows up anyway. HASP can rewrite known managed values in output paths it controls, and hasp check repo can scan a repo for managed values that landed in files. Use hasp check repo before commits, releases, or support bundles. Use git hooks from hasp project bind or hasp setup when you want the check to run before a commit. Where a secret should live Use this order when you choose a delivery path: delivery path Vault + broker The value stays behind HASP until delivery. hasp run A child process receives environment values. hasp inject A command receives environment values or temp files. hasp write env A repo visible env file is written on purpose. reveal or copy Plaintext leaves the broker for manual use. Prefer the first path that lets the work finish. Move down the list only when the tool requires more exposure. 1. Keep the value in the vault and let the broker resolve it. 2. Pass the value to a child process environment with hasp run. 3. Materialize a temp file with hasp inject when a tool requires a file path. 4. Write a repo env file with hasp write env after a human accepts that exposure. 5. Reveal or copy plaintext for manual work, then rotate if you pasted it into an unsafe place. The first three paths keep the repo cleaner. The last two paths trade safety for convenience. Common mistakes Treating the vault as the policy The vault stores values. Project bindings and grants decide use. If a command fails because a value is not visible in a repo, add or inspect the binding. Do not copy the value into .env as a workaround. Binding the wrong directory Bind the repo root you want to protect. A nested package, a generated folder, or a parent workspace can give you the wrong boundary. Use hasp project status project root . to see what HASP thinks the project root is. Giving agents plaintext Agents can quote, summarize, write, and log. A plaintext secret in the agent context is hard to reason about after the fact. Use references and brokered tools. If you must reveal a value while an agent is active, use hasp session grant plaintext and keep the grant short. Writing convenience files before you mean to hasp write env exists because some tools require .env. Use it after you decide that a repo visible file is acceptable. If the workflow can run through hasp run or hasp inject, use those first. How to choose the first command Use hasp setup for a guided first run. Use hasp secret add when the vault exists and you want to add one value. Use hasp import when the value already lives in .env, JSON, or pasted shell export text. Use hasp project bind when the repo boundary is missing. Use hasp agent connect when a coding agent needs a profile. Use hasp proof when you want to confirm that the current repo can receive one brokered value. Use hasp doctor when you expected a flow to work and it did not. Reading error messages Most HASP errors point at one missing object: vault errors mean HASP cannot open the encrypted store binding errors mean the repo has no visible reference daemon errors mean the local broker is not reachable permission errors mean a grant, session, or plaintext exception is missing repo check errors mean a managed value appeared in a file Fix the missing object. Avoid working around the boundary with copied plaintext. For exact terms, use the Glossary.


================================================================================
Start / Agent mental model
URL: https://gethasp.com/docs/v1.0.4/agent-mental-model/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/agent-mental-model.md
--------------------------------------------------------------------------------

Agent mental model An agent treats HASP as the route for brokered work. Teach the agent one habit: ask for the work to happen, not for the value. The agent names a repo, a safe reference, and a command. HASP checks the project, grant, session, and target. The child process gets the secret if the request passes. The agent gets the command result and the audit trail keeps the record. Use the Mental model for the operator view. This page shows the same flow from the agent side. The agent sees handles An agent working through HASP sees a smaller world than a shell with .env loaded. That smaller world is the point. agent surface Prompt Use @OPENAI API KEY through HASP. Do not paste the value. Tool list hasp list , hasp run , hasp inject , hasp redact Broker Checks repo, session, grant, and reference. Output Status, stdout, stderr, and a local audit event. Secret value Stored in the vault. Delivered to the child process only. The handle can appear in the transcript. Keep the value out of prompts, logs, and files the agent can read. The agent can reason with these objects: named refs such as @OPENAI API KEY neutral aliases such as secret 01 manifest targets such as server.integration tool results from hasp list, hasp targets, or hasp target explain command output from hasp run or hasp inject The agent asks for plaintext only when the brokered route cannot run the task. One run from the agent's seat Imagine a repo with a test command that needs OPENAI API KEY. timeline with prompt and tool annotations 1 User prompt Run the integration tests. Use HASP for OPENAI API KEY. The user gives the agent a handle and a boundary. 2 Agent lists refs hasp list {"project root":"."} The agent confirms which refs this repo can name. 3 Agent asks for work hasp run {"env":{"OPENAI API KEY":"@OPENAI API KEY"},"command":["pnpm","test:integration"]} The tool call names a command and a ref. It leaves plaintext behind HASP. 4 HASP checks policy repo + session + grant + ref The broker rejects the request if any check fails. 5 Child process runs OPENAI API KEY=... pnpm test:integration The process gets the environment value. The agent sees only output. 6 Agent reports result exit=0, tests passed, audit event written The agent can summarize the run without learning the key. The agent's best request is a brokered action. The value moves only between HASP and the child process. The transcript can now show the whole decision trail: No one had to paste the key into the chat. The prompt shape Good prompts give the agent a task, a repo boundary, and a delivery rule. That prompt gives the agent enough room to work. It also tells the agent how to fail. Use this shorter version when the repo already has targets: Where MCP fits MCP is the tool lane agents already understand. HASP occupies that lane as the broker between tool calls and vault values. mcp broker path Agent Calls MCP tools by name. JSON RPC HASP MCP hasp mcp or hasp agent mcp <id> policy Broker Checks repo, session, grant, target, and ref. Child process receives the value. The agent receives stdout, stderr, exit code, redaction flags, and audit backed metadata. MCP is the transport. HASP still owns the secret boundary. There are two commands to know: hasp mcp starts the generic stdio MCP server. hasp agent mcp starts the same tool surface with profile aware session setup. Use the profile aware command for first class agents such as Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. It opens or reuses a daemon backed session, labels the caller as agent: , sets the project root when the profile has one, and enables agent safe mode for protected workflows. Generic MCP config looks like this: Profile aware config uses the agent command: If the agent launches helpers that also call HASP, start the agent through hasp agent launch or hasp agent shell . The launcher pushes HASP SESSION TOKEN and safe mode metadata into the whole child process tree, including helpers outside the MCP server process. MCP handshake A strict MCP client starts with initialize, then asks for tools, then calls one tool at a time. stdio mcp sequence 1. initialize {"method":"initialize","params":{"protocolVersion":"2025 06 18"}} HASP returns a negotiated protocol version, tool capability, and server name. 2. tools/list {"method":"tools/list"} The agent sees tool names, descriptions, and JSON input schemas. 3. tools/call {"method":"tools/call","params":{"name":"hasp run","arguments":{...}}} HASP runs the brokered action or returns a JSON RPC error. HASP ignores MCP notifications without an id. That keeps clients from seeing extra replies on the stdio stream. Test the generic server without opening an agent: Test a profile aware server the same way: For a full handshake: The default response lists these tools: Tool Agent use hasp list List project scoped refs and safe named refs. hasp check Scan the project for managed values that leaked into files. hasp targets List sanitized manifest targets, delivery kinds, refs, and prerequisite status. hasp target explain Explain one target without command argv or values. hasp run Run a command with secret refs mapped into environment variables. hasp inject Run a command with secret refs mapped to broker owned credential files. hasp secret get Confirm metadata and get a safe named ref. It returns no raw value. hasp redact Redact managed values from text before quoting logs. MCP arguments that matter Most HASP MCP tools accept the same broker fields: project root binds the request to a repo. If omitted, HASP uses HASP AGENT PROJECT ROOT or .. session token lets a wrapper pass an existing daemon backed session. If omitted, profile aware MCP opens one. host label names the caller in audit events. Profile aware MCP uses agent: . grant project can be once, session, or window. grant secret can be once, session, or window. Use window for project approval when an agent will run several related tools inside one repo. Use session for secret access when the same run will call a test, retry, and inspect logs. Use once when the command has a narrow, single shot shape. MCP tool calls A basic brokered run uses three calls. First, it asks what the repo can name: Then it runs the command with an environment ref: If the tool needs a credential file, the agent uses hasp inject: Those calls keep the agent focused on the job. The agent names a ref and a command. HASP owns resolution. Tool results hasp run and hasp inject return the command result: HASP streams command output through the redactor before the agent sees it. It also caps each stream, so a noisy process stops at a bounded response size. If the agent sees redacted: true, it can report that HASP removed a managed value from the output. If it sees stdout truncated or stderr truncated, it reports the visible output and the omitted byte count. Manifest target calls add target metadata: Targets keep the agent from inventing secret mappings. hasp targets and hasp target explain return sanitized descriptions, refs, delivery kinds, destination names, prerequisite status, and the manifest identity. They leave out raw values and repo controlled command argv. MCP execution refuses two target shapes: a target combined with extra env or files mappings a target that writes workspace visible secret files, such as generated xcconfig output Each refusal points the agent back to a human CLI flow for workspace visible artifacts. Trusted harness tools The default MCP catalog avoids tools that accept raw values or mutate vault state. A trusted local harness can opt in with: That adds: hasp capture hasp secret add hasp secret update hasp secret delete hasp secret expose hasp secret hide Keep those tools out of normal agent configs. They exist for local setup, controlled evals, and migration harnesses. Day to day agents use hasp run, hasp inject, hasp secret get, and hasp redact. Choose the path agent decision chart Need to discover refs? Call hasp list or hasp targets . Need an env var? Call hasp run with env mappings. Need a credential file? Call hasp inject with files mappings. Need to clean output? Call hasp redact before quoting logs. Need plaintext? Stop and ask for an operator decision. Protected flows block reveal and copy until the operator grants a short exception. Pick the first tool that can finish the work. Plaintext is an operator action, not an agent shortcut. For repo defined workflows, prefer manifest targets. Targets let the repo name the expected refs once, and the agent can call a stable target instead of rebuilding the mapping by memory. If the agent only knows a secret name, it can ask for metadata first: The result can include named reference: "@OPENAI API KEY" and available in project: true. It still omits the raw value. Blocked run reports A failure report names the missing piece. For an expired session: For a tool that expects a file: The agent reports the broker decision and stops there. Copying a key into .env changes the security story and leaves cleanup work behind. MCP errors use JSON RPC error responses. Read the message field: Translate that into a developer facing report: Transcript rules for agents Use these rules in agent instructions, project docs, or a system prompt: These rules give the agent a narrow protocol. They also give the developer a readable transcript: the agent asked for a ref, HASP checked policy, the command ran, and the agent reported the result. Review an agent run After the run, check three places: 1. The transcript contains refs, commands, and output. Secret values stay out. 2. The audit log shows the session, grant, reference, and delivery path. 3. The repo stays clean. Run hasp check repo if the agent wrote files. If all three pass, the agent used HASP the way a developer expects: enough access to finish the task, no raw value in the agent context.


================================================================================
Start / Value-free manifests
URL: https://gethasp.com/docs/v1.0.4/value-free-manifests/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/value-free-manifests.md
--------------------------------------------------------------------------------

Value free manifests HASP can read one committed repo contract: The file lives at the project root. You commit it so a teammate, CI job, app profile, or coding agent can see what the repo expects. The file does not store secrets. It stores names, refs, target names, delivery names, paths, and placeholder example locations. That distinction matters. A manifest can help the repo explain itself without turning git into a secret store. A committed value free manifest can describe requirements and targets. The short version A value free manifest answers two questions: Which refs does this repo expect? Which target gets which subset? It does not answer these questions: Does this machine have the value? Is this repo bound to that value? May this command receive the value right now? May an agent read the plaintext? The vault, project binding, grant, and broker answer those questions later. Treat the manifest as repo input. It describes a request. It is not authority. The sentence, word by word "A committed value free manifest can describe requirements and targets" has a specific meaning in HASP: committed: the file is normal repo metadata. It can live in git, go through review, and travel with the project. value free: the file contains no plaintext secret values and no local grant decisions. It can name things, but it cannot contain the things themselves. manifest: the file is a machine readable contract, not a README convention. HASP parses it, validates it, and uses it to drive commands. requirements: the repo declares the refs it expects, their kind, whether they are required, and how reviewers should classify them. targets: the repo declares named workflows, and each workflow receives only the refs and delivery names listed for that target. The sentence does not mean a checkout can use the values by having the file. It means the checkout can explain what it needs. The machine still needs matching vault items. The repo still needs a binding. The run still needs grants. The broker still decides whether and how to deliver. Why commit the file Without a manifest, a new developer learns required secrets from failures, old README text, .env.example, app code, or another person. That works until the repo grows. A repo may have local development, integration tests, and release scripts. They may share one underlying vault item but need different delivery names: The manifest lets the repo say that in one place. The value stays in the local vault. The manifest says what shape each workflow expects. What value free means Value free means no plaintext credential material and no local approval state. Do not put these in .hasp.manifest.json: API keys, passwords, tokens, certificates, private keys, cookies, session IDs, or connection strings fields named value, values, grant, grants, convenience grants, tokens, session token, or workspace trust local hook state local session state local vault file paths user specific absolute paths workspace trust decisions shell snippets that compute secrets HASP rejects the local authority field names above, even when they appear deep inside the JSON tree. Value free does not mean metadata free. A target named release.sign or an item name such as STRIPE LIVE SECRET KEY can reveal how the repo works. Use neutral aliases when provider names or environments would leak too much. The file HASP reads HASP V1 reads JSON. The filename is fixed: The file sits at the bound project root, not in each package. Use one project binding for one repo boundary. Use targets inside the manifest for app, platform, test, and deploy workflows inside that repo. Use a second project binding only when you need a separate trust boundary, such as a sibling repo or a sub root that must not share refs. Complete example This manifest describes three targets: server.dev receives the env vars used by local server work. server.integration receives a narrower set for integration tests. release.sign receives a file credential path for release packaging. No value appears in the file. Field by field version Use "v1" when the manifest declares requirements, targets, project metadata, or target examples. HASP rejects other versions. project project.name and project.description are optional human labels. Keep them plain. Do not put tenant names, customer names, incident names, or private host names in these fields unless the repo already exposes that metadata. references references maps repo facing aliases to vault item names. The alias is what repo workflows can request. The item is the name of the local vault item. The manifest can use a neutral alias such as secret 01, then operators can keep provider specific names in their local vault. Requirements and delivery entries can refer to an alias: They can also refer to a named ref: The named ref form still requires a matching references entry. HASP does not let a target invent a new ref by writing @SOMETHING in delivery. requirements A requirement says one ref should exist for this repo. ref must match a declared reference. kind is kv or file. classification is secret or public config. Use secret for values that must stay out of files, logs, prompts, and client bundles. Use public config only for values you would be willing to ship to a client app or publish in an example file. The label does not make a value safe. It tells HASP which placeholder to generate and gives reviewers a warning. targets A target is a named workflow inside the repo. Examples: Target names must start with a lowercase letter or digit. They can contain lowercase letters, digits, dots, underscores, and hyphens. They cannot contain slashes, backslashes, control characters, or more than 64 characters. HASP treats target names case insensitively for duplicate checks. server.dev and Server.Dev conflict. target.root root is the working directory for that target, relative to the project root. Use "." or omit the field for the project root. HASP resolves symlinks when it validates paths. A target root, generated output, or example path cannot escape the project root. target.command command is an argv array: Do not use shell strings such as "pnpm dev". HASP rejects empty command arguments and control characters. It also does not run this command when it loads, inspects, or validates the manifest. hasp run target server.dev can use the command. If a target has no command, you can pass one after . target.delivery Delivery entries map a ref to a destination name for one target. as can be: env file xcconfig name must look like an environment variable: it starts with a letter or underscore and then uses letters, digits, or underscores. HASP rejects dangerous destination names because they can alter process behavior instead of configuring your app: PATH LD PRELOAD NODE OPTIONS PYTHONPATH RUBYOPT SSH AUTH SOCK HOME SHELL names starting with DYLD names starting with GIT names starting with HASP File requirements can only be delivered with "as": "file". HASP rejects a file item delivered as an env var or xcconfig value. target.delivery.output output is allowed only for xcconfig delivery: This declares where hasp write env target build.config should write a generated file. It does not write the file during inspection. It also does not make file materialization the preferred path. Use runtime delivery when the tool can accept env vars or broker owned temp files. target.examples Examples describe placeholder files that HASP can check or generate: Supported formats are env and xcconfig. Generated examples use placeholders: HASP SECRET for secret key value requirements HASP PUBLIC CONFIG for public config requirements HASP FILE for file requirements HASP writes a marker into generated examples. It refuses to overwrite a hand authored file silently. default capture policy The manifest may include default capture policy. Local binding state wins if the project already has a local default. Use this field only as a repo level default for new capture flows. Do not use it for grants. What HASP does with the manifest Inspect requirements HASP reads requirements, checks whether refs are present and exposed, and may suggest hasp secret add commands. It does not print values. It does not run target commands. Inspect targets Target inspection lists names, refs, delivery kinds, examples, and whether a command exists. Agent facing MCP target listing is narrower: it omits target command argv and secret values. Check the project Project doctor reports manifest diagnostics with codes and booleans. It avoids raw command output, command argv, socket paths, and secret values. It can report problems such as: unavailable target commands stale examples generated outputs that are not ignored workspace visible secret delivery requirement kind mismatches target drift Generate examples check compares the expected placeholder file with the file on disk. write creates or updates generated examples. HASP never resolves real vault values into examples. Run a target HASP expands only the delivery entries declared by server.dev. It then uses the normal broker path. The project binding, grant, redaction, and audit checks still apply. When you use target, hasp run rejects extra env or file mappings. The manifest target owns the delivery set for that run. If a target has no command, pass one after : Inject a target into another command Use this when the manifest should provide env or file refs, but you want to choose the command at runtime. Write a generated value file This writes plaintext into a workspace visible generated file. Use it when a tool needs a real file. Prefer run or inject when they work. Seed an app profile app connect target copies the target command and delivery mapping into a local app profile. The app profile is local state. If someone changes the manifest later, HASP does not rewrite the saved profile behind your back. Drift review HASP records a local review for target expansion outside git. It hashes the target command, refs, delivery, and outputs. If the committed manifest later changes those pieces, human CLI flows warn before continuing. hasp project doctor json reports target drift. This catches changes such as: server.dev starts asking for a new ref a target command changes a generated output path changes a delivery name changes from DATABASE URL to another destination The review record lives in local HASP state. It is not committed. Rules HASP enforces HASP validates manifests before it uses them: version must be v1 when extended fields appear. Requirement refs must be unique. Requirement refs must be declared in references. Requirement kind must be kv or file. Requirement classification must be secret or public config. Target names must match HASP's safe target name pattern. Target names cannot conflict by case. Target roots, generated outputs, and example paths must stay inside the repo. Target commands must be argv arrays with non empty safe arguments. Delivery format must be env, file, or xcconfig. Delivery destination names must be variable shaped and not dangerous. Delivery names cannot repeat inside one target. Delivery refs must point at known requirements. File requirements can only use file delivery. output is allowed only for xcconfig. Example format must be env or xcconfig. Secret or local authority fields are rejected anywhere in the JSON tree. These checks do not prove the command is safe. They keep the manifest inside the contract HASP can reason about. Metadata rules Use the same care you use for .env.example, README setup notes, and CI configuration. Safe enough for most repos: neutral aliases such as secret 01, file 01, config 01 target names such as server.dev, server.integration, test.integration destination names the app already uses, such as DATABASE URL generated example paths inside the repo Review before committing: provider names production environment names customer names tenant IDs private hostnames incident names deploy topology in descriptions Do not rely on the manifest to hide metadata from someone who can read the repo. The manifest hides values, not the fact that a workflow exists. Common mistakes Putting the real value in item Wrong: Right: item is the vault item name. It is not the value. Treating a target as authorization A target narrows the delivery set. It does not approve access. This command still needs grants: Delivering a file item as env text Wrong: Right: File delivery gives the command a path to a broker owned temp file. Using dangerous env names Do not use a manifest to set PATH, LD PRELOAD, NODE OPTIONS, DYLD , GIT , or HASP . HASP rejects these names because they can change the runtime or the broker itself. Expecting generated examples to contain values Generated examples contain placeholders only. They exist for framework compatibility and onboarding. They are not a secret delivery path. Minimal manifest Start small: Then run: When those read cleanly, connect an app or run the target through the broker: or:


================================================================================
Start / Install
URL: https://gethasp.com/docs/v1.0.4/install/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md
--------------------------------------------------------------------------------

Install HASP Use Homebrew for normal installs on macOS and Linux. Use the packaged release scripts when you need to verify a tarball by hand or install into a custom prefix. Install with Homebrew The formula is the released CLI path. If you already added the tap, brew install gethasp/tap/hasp is enough. After install, continue with After Install: Install with the script Use the hosted script when you want the current signed release without adding the Homebrew tap: The script prints each install phase, verifies signed release metadata and artifacts, installs hasp to $HOME/.local/bin/hasp by default, then prints the installed version. In an interactive terminal it asks whether to start hasp setup immediately; the default answer is yes. For automation, set HASP INSTALL RUN SETUP=0 to skip the prompt or HASP INSTALL RUN SETUP=1 to start setup without asking. Upgrade with Homebrew Run hasp doctor after upgrading if a daemon is already running. It reports CLI and daemon version mismatch. Uninstall with Homebrew Homebrew removes the formula files. It does not remove your HASP vault, HASP HOME, repo hooks, app launchers, or audit history. Remove those only when you are intentionally decommissioning the local install. Direct packaged release Use this path when you downloaded a release tarball and want local signature verification before install: Default install prefix: Installed binary: Upgrade a packaged release You can also use the CLI upgrade command when you want HASP to fetch and verify a published release: Uninstall a packaged release The default uninstall path removes the installed release tree only. Pass remove hooks from or purge hasp home only when that cleanup is intentional. Source build Use source builds for development: Source builds are not the normal user install path.


================================================================================
Start / After Install
URL: https://gethasp.com/docs/v1.0.4/after-homebrew/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md
--------------------------------------------------------------------------------

After Install This guide is for the most common starting point: you already installed HASP you want HASP working with your coding agent today If that is you, start with the guided setup: hasp setup is the normal path after install. It can choose: where local encrypted HASP data lives on this machine machine defaults for automatic project protection which coding agents should be configured for MCP, or whether to skip that for now whether you want to add a vault secret and connect one app before setup ends repo binding and broker proof when you run it inside a project a final review step before HASP writes local changes You should not have to manually run hasp init, hand edit MCP JSON, or bootstrap every repo before HASP is useful. Those lower level commands still exist for scripts, recovery, and exact control. After machine setup, HASP can automatically adopt a project the first time you use HASP inside it. Repo scoped bindings still exist under the hood, but they are created for you from machine defaults instead of requiring manual setup first. The rest of this page starts with the simple daily surface, then shows the manual flow and troubleshooting fallback. The normal path is guided The installed path is designed around one guided command followed by normal work. The product model is: one personal vault connect apps once connect agents once run apps and agents normally afterward That means the easy surface should start here: hasp setup hasp secret add hasp app connect hasp agent connect project root . After an app is connected, the normal run command is: hasp app run You should not need repeated command wrapping or repeated repo/bootstrap thinking for normal work. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. Manual fallback and advanced control The following sections are for scripts, recovery, exact broker testing, and operator control. If hasp setup already got you to a connected app or agent, you can skip to what you do day to day. 1. Confirm the install Run: You should see a real path and a version number. If hasp is not found, restart your shell or make sure the install directory's bin path is in your PATH. 2. Set your local password HASP needs one local master password so it can open your encrypted vault. For this shell session: Optional: If you do not set HASP HOME, HASP uses its default local directory. 3. Initialize your vault Run: That creates your local encrypted vault. 4. Import one real secret The easiest path is to import an existing file. Example .env file: Example JSON credential file: If you want the direct terminal path, use: If you already have a secret file or shell snippet, the import path still works: That is safer than leaving it in shell history or dropping it into a repo file. 5. Bind one repo Go into one repo you use with an agent: Now bind a safe alias to one imported secret: What that means: OPENAI API KEY is the real imported secret name in the vault secret 01 is the safe alias you expose to the repo and agent workflow codex cli picks the first class integration defaults for Codex CLI If you are using a different first class agent, swap the profile: claude code cursor aider codex cli openclaw hermes If you just want to save a secret and make it available in the current repo, the simpler path is: If your agent is not first class, use: 6. Test the broker before touching your agent Run one brokered command first: If that succeeds, HASP is working. What the flags mean: env OPENAI API KEY=@OPENAI API KEY Put the named ref @OPENAI API KEY into the command as OPENAI API KEY grant project window Reuse approval for this project for a time window grant secret session Reuse approval for this secret in the current session grant window 15m Keep that project approval open for 15 minutes 7. Connect your coding agent For first class agents, the common pattern is the same: HASP runs as a local stdio MCP server the command is hasp mcp Generic MCP config shape: Use the matching profile doc for your agent: Codex CLI Claude Code Cursor Aider Generic compatible profile docs: OpenClaw Hermes Before opening your agent, test the MCP server directly: If you see the HASP tools, your agent should be able to connect. 8. What you do day to day Start with saved app and agent profiles. You should not need to rebuild the long broker command for normal work. Easy path Run a connected app: Add another secret: Connect another app when you need one: Connect or refresh an agent profile in the current repo: Review activity: Advanced: one off command delivery Use hasp run when you do not have a saved app profile yet or when a script needs an exact one off mapping: Prefer the easy app/agent commands when they fit. Use this broker form when you need to spell out the project, env mapping, and grant window yourself. Advanced: materialize a file only when a tool needs one Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. 9. Backup your vault Do this before you get comfortable. If you ever need to restore: 10. What not to expect HASP helps a lot, but do not expect magic. It reduces common local leaks. It does not protect you from a malicious same user local process. It does not make pasted secrets magically safe after the fact. write env is explicit convenience. Once HASP writes a real file, the OS, editors, backups, and git hooks can all see it. 11. If something is broken hasp says it needs a master password Set: Your agent cannot connect to HASP Test: If that fails, fix HASP first before debugging the agent. Your repo moved or changed paths Run bootstrap again in the new repo root: A command keeps prompting too often Use a project window: You are not sure what profile to use Start with: your real agent profile if it is listed generic if it is not 12. The shortest successful setup The easiest successful path is guided: If those commands work, you are ready to use HASP through your connected app or coding agent. If you need a fully explicit scriptable proof instead, use the advanced form: Use this form for automation, recovery, or debugging a specific lower level layer.


================================================================================
Operate / Command guide
URL: https://gethasp.com/docs/v1.0.4/command-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/command-guide.md
--------------------------------------------------------------------------------

Command guide This guide explains the whole command surface in product terms. Use hasp help when you need the exact flags for your installed build. The command names fall into a few jobs: create local state add or expose secrets connect apps and agents run brokered commands inspect, repair, and recover Most command choices come down to the object you are changing: vault state, secret state, project boundaries, delivery, consumers, or repair evidence. First run commands hasp setup Use hasp setup when you want HASP to guide the machine through the first useful state. It can create the vault, choose HASP HOME, import local secrets, bind a project, connect an agent, install repo hooks, and print the first proof command. Interactive setup asks before it writes convenience files or launchers. Non interactive setup needs enough flags or environment variables to avoid prompts. Closest commands: hasp init creates the vault. hasp project bind creates the repo binding. hasp bootstrap handles repo first agent setup for operators. hasp secret add starts with one value instead of a whole setup flow. Use this for a new laptop, a new HASP HOME, or the first install in a repo: Use this for CI like setup where prompts would hang: hasp init Use hasp init when the local encrypted vault is missing. It creates the vault under HASP HOME. It does not bind a repo, connect an app, connect an agent, import values, or install hooks. That narrow behavior makes it useful in scripts and tests. Closest commands: hasp setup can call the same kind of vault creation as part of a guided flow. hasp restore backup creates vault state from an encrypted backup. hasp status tells you whether a vault exists and whether HASP can open it. hasp bootstrap Use hasp bootstrap when an operator wants to prepare a repo and an agent profile in one command. Bootstrap is repo first. It binds the project root, applies aliases, binds imported or existing items, installs hooks when requested, and verifies the profile. It works well for teams that want a repeatable local setup command. Closest commands: hasp setup is the guided human flow. hasp agent connect connects an agent profile after the vault and repo already exist. hasp project bind gives you a binding without agent profile work. hasp bootstrap profiles Use this to list known agent profiles and their support state. Use the output to choose a first class profile, a generic MCP path, or a custom command wrapper. hasp bootstrap generic Use this when an agent can run an MCP or CLI command, but HASP does not ship a first class profile for it yet. It binds the repo and writes a generic compatible profile using hasp mcp as the transport. hasp bootstrap doctor Use this to diagnose a bootstrapped repo/profile pair. It checks whether the repo, binding, profile config, and proof path still match. hasp bootstrap print config Use this when a generic agent needs a config snippet you can paste into its own settings file. It prints formats such as stdio JSON, Cursor JSON, Codex TOML, and Claude JSON for the generic compatible path. hasp doctor Use hasp doctor when you expected HASP to work and one layer is broken. Doctor checks daemon reachability, vault access, project binding, repo hooks, audit state, and version mismatch between CLI and daemon. JSON output uses an allowlist so it does not expose reconnaissance heavy local details. Closest commands: hasp status prints state, but it does less diagnosis. hasp ping checks daemon reachability. hasp bootstrap doctor focuses on one profile bootstrap. Secret lifecycle hasp import Use hasp import when the secret already exists in a .env file, JSON credential file, clipboard paste, or shell export snippet. Import parses the source and writes vault items. With preview, it shows what it would import without changing the vault. With bind, it also exposes imported items to a project binding. Closest commands: hasp secret add is better when you want to enter one new value. hasp set is a deprecated scripting alias for one value. hasp write env moves in the opposite direction by writing vault values back to an env file. hasp secret Use hasp secret as the root for item lifecycle commands. It covers adding, updating, rotating, deleting, listing, diffing, exposing, hiding, and controlled plaintext access. hasp secret add Use this to create a new vault item. Interactive mode prompts for the value. Scripted mode can read from stdin or a file. Inside a repo, HASP asks for explicit exposure. That rule prevents a new secret from becoming visible to the wrong project because you ran the command in a terminal that happened to sit in a repo. Closest commands: hasp import handles many values or structured files. hasp secret update changes an existing item. hasp secret expose makes an existing item visible to a repo. hasp secret update Use this to replace an existing item while keeping its identity. Update is the right command when the provider issued a new value and you want the same name and bindings to keep working. Closest commands: hasp secret rotate records a rotation style replacement. hasp secret add creates a new item. hasp secret delete removes the item. hasp secret rotate Use this when you replace a value because the old one should stop being trusted. Rotation helps separate normal edits from incident or lifecycle replacement. Use it with provider side rotation. HASP can update the local item, but the upstream provider still controls whether the old credential remains valid. Closest commands: hasp secret update replaces a value without the rotation meaning. hasp audit secret helps inspect recent use before or after rotation. hasp session revoke all cuts local active sessions after a rotation. hasp secret delete Use this when the item should leave the vault. Delete removes the local item. If other repos used aliases or exposures for that item, inspect those bindings so stale references do not confuse future runs. Closest commands: hasp secret hide removes repo visibility while keeping the vault item. hasp vault lock locks access without deleting data. hasp export backup should run before deletion when you need a recovery point. hasp secret list Use this to see managed items and visible references. List is the safest first inspection command because it prints metadata, not raw values. Closest commands: hasp secret show inspects one item. hasp project status shows repo binding visibility. hasp audit shows historical actions. hasp secret get and hasp secret retrieve Use these for metadata oriented access to one item. retrieve is an alias for get. Keep these in scripts when you need structured item details. Use reveal or copy when you need plaintext. Closest commands: hasp secret show is human facing metadata. hasp secret reveal prints plaintext after the proper checks. hasp secret copy writes plaintext to the clipboard after the proper checks. hasp secret show Use this when a human wants to inspect one item without reading the value. Show answers questions such as kind, visibility, and references. It should be the default inspection command during support work. hasp secret reveal Use this when a human must print the raw value. Reveal carries more risk than show. In protected agent workflows, HASP blocks raw reveal unless an operator grants a short plaintext exception. Closest commands: hasp secret copy avoids terminal output by writing to the clipboard. hasp run passes the value to a child process without printing it. hasp session grant plaintext creates the temporary exception for protected flows. hasp secret copy Use this when you need plaintext in the clipboard rather than stdout. Copy has the same safety concerns as reveal. The clipboard is still plaintext. Prefer brokered delivery for commands and agents. hasp secret diff Use this to compare a repo visible env file or candidate source against managed values. Diff helps when you are migrating a repo away from .env. It shows which values match HASP managed items and which values remain unmanaged. Closest commands: hasp check repo scans for managed values that leaked into files. hasp import preview shows what HASP would import. hasp write env writes selected managed values back to a file. hasp secret expose Use this to make an existing vault item visible to a repo. Expose creates or updates the project binding view. The repo can then ask for the item by the exposed reference or alias. Closest commands: hasp secret add expose=always creates and exposes in one step. hasp project bind alias name=item adds aliases while binding a project. hasp secret hide removes repo visibility. hasp secret hide Use this to remove repo visibility while keeping the item in the vault. Hide is safer than delete when the value still belongs on the machine but one project should stop seeing it. hasp set Use hasp secret add for new work. hasp set remains for one release compatibility with older scripts that add or replace a single value without prompts. hasp capture Use hasp secret add for new work. hasp capture is the older broker oriented value capture command. It can save a value and bind it to a repo with grants. New docs and scripts should move to hasp secret add with explicit exposure. Project boundaries hasp project Use hasp project to manage repo boundaries. Project commands decide where a secret can be requested. They do not create provider credentials and they do not run commands. hasp project bind Use this to bind one repo root. Bind records the project root, default policy, aliases, and git hook preference. By default, HASP expects a git repo. Pass allow non git when you want a non git directory as the boundary. Closest commands: hasp setup project root . can bind during first run. hasp bootstrap project root . binds and connects an agent profile. hasp project adopt binds many repos under a parent directory. hasp project status Use this to inspect what a repo can see. Status shows the binding, aliases, visible references, hooks, and default policy for a project root. hasp project unbind Use this to remove the project boundary. Unbind does not delete vault items. It removes the repo's access path to those items. hasp project adopt Use this for workspaces with many repos. Adopt scans under a directory for git roots and binds each candidate with the current project defaults. Run preview first. hasp project requirements Use this to inspect the value free manifest contract for a repo. Requirements output shows refs, kinds, target usage, and whether the local vault has and exposes each item. It may suggest hasp secret add commands for missing items, but it never prints values or runs target commands. hasp project targets Use this to list manifest targets without exposing secret values. hasp project examples Use this to check or write placeholder example files such as .env.example. Generated examples contain placeholders only. They do not resolve vault values. hasp project doctor Use this for project specific manifest diagnostics. hasp project doctor json uses a separate safe schema from top level hasp doctor json. It reports diagnostic codes and booleans, not values, socket paths, raw command output, or environment dumps. It also reports target drift, unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, and vault kind mismatches without printing command argv or value paths. hasp check repo Use this before commits, releases, or support bundles. Check repo scans files for managed values. It catches the failure mode where a value controlled by HASP appears in the repo anyway. Closest commands: hasp secret diff compares a candidate env file with managed values. git hooks from hasp project bind can run this before commits. hasp redact exists as a hidden stream filter for managed values. Brokered delivery hasp run Use hasp run when a normal command needs secret values as environment variables. Run resolves references, applies project and secret grants, starts the child process, and keeps managed values out of the repo. It is the default safe path for CLIs that read env vars. Closest commands: hasp inject also handles temp file credentials. hasp write env writes a persistent env file. hasp proof wraps a small run to test the brokered path. When a repo has targets in .hasp.manifest.json, use target to expand only that target's declared delivery subset: Use dry run to inspect the execution plan. Use explain when you need a structured explanation of what HASP would resolve. hasp inject Use hasp inject when a command needs env vars, files, or both. Some SDKs refuse env content and require a credential file path. Inject can materialize file refs for the command lifetime and point an env var at that file. Closest commands: hasp run fits commands that need env vars and no temp files. hasp write env creates a persistent file by design. hasp app run applies a saved app consumer profile. Target injection is useful for file shaped credentials: hasp write env Use hasp write env when you accept a repo visible env file. Write env exists for tools that do not work with brokered env injection. It should be explicit in scripts and review notes because it materializes secrets into a file. Closest commands: hasp run avoids writing a file. hasp inject creates temp files for one command. hasp check repo can catch managed values after accidental writes. write env target can materialize a configured target output, but it still requires explicit convenience approval: hasp proof Use hasp proof to confirm that a repo can receive one brokered value. Proof replaces the long first run one liner with a named command. It checks the practical path: vault item, repo binding, grant, and child process delivery. Closest commands: hasp run gives you the full execution surface. hasp doctor diagnoses layers after proof fails. hasp project status shows the binding side of the proof. Apps hasp app Use hasp app when a local application needs managed secrets. An app consumer stores a name, command, project root, and mappings. After connection, hasp app run can execute it with the right brokered values. hasp app connect Use this to create or update an app profile. Connect binds the project if needed, records env/file/dotenv mappings, and can install a launcher under HASP HOME/bin after explicit consent. Closest commands: hasp run is better for one off commands. hasp app install installs a launcher for an existing app profile. hasp agent connect handles coding agents, not app commands. When the repo manifest declares a target, an app profile can be seeded from that target. The saved profile is local state and does not silently change when the manifest changes later. hasp app run Use this to run a connected app profile. Run reads the saved app mappings and executes the app through the broker. hasp app install Use this when you want a stable launcher on PATH. Install writes a launcher script for an app profile. The launcher calls HASP so normal app startup still gets brokered secrets. hasp app shell Use this when you want an interactive shell with the app profile's managed environment. Shell helps with local debugging. Treat the shell as sensitive because child commands can read the injected environment. hasp app disconnect Use this to remove an app consumer. Disconnect removes the app profile and its launcher state. It does not delete vault items. hasp app list Use this to inspect configured app consumers. Agents hasp agent Use hasp agent when a coding agent needs brokered access. Agent commands connect profiles, serve MCP, launch wrappers, and list support status. hasp agent connect Use this to connect one agent profile to a project. Connect writes the local profile state and config needed for the agent to reach HASP. hasp setup agent writes the same managed agent state when setup configures an agent for a repo. The profile decides whether the best path is first class MCP, a wrapper, or a generic compatible config. Closest commands: hasp bootstrap profile does repo first setup plus verification. hasp mcp serves the generic MCP surface. hasp app connect is for app commands, not coding agents. hasp agent mcp Use this as the profile aware MCP server command for an agent. It opens or uses a daemon backed session for the profile and project, then serves the MCP tool surface. hasp agent launch Use this when you want HASP to start the agent process. Launch can propagate HASP session metadata to child processes. That gives stronger coverage than an agent you start outside HASP with the MCP command alone. hasp agent shell Use this to open a shell that carries the agent safe session context. Shell helps when the agent or its helper commands need inherited HASP session state. hasp agent disconnect Use this to remove an agent connection. Disconnect removes local profile state. It does not delete vault items or project bindings. hasp agent list Use this to see connected agents. hasp agent list supported Use this to see profiles HASP knows about and how complete their support is. Use it to choose between first class profile support and the generic MCP path. hasp mcp Use this as the generic MCP server command. hasp mcp is the low level stdio server. Profile aware commands such as hasp agent mcp codex cli add agent specific session behavior around the same idea. Sessions and plaintext exceptions hasp session Use hasp session to inspect or control broker sessions. Most workflows manage sessions for you. Session commands are for debugging, incident response, and explicit plaintext exceptions. hasp session open Use this to open a broker session by hand. Manual sessions help when you are debugging MCP or wrapper behavior outside the normal agent launcher flow. hasp session list Use this to inspect active sessions. mine filters to sessions owned by the local user. hasp session resolve Use this to inspect what a session token points to. Resolve helps diagnose token propagation and project root mismatches. hasp session revoke Use this to shut down one session or all active sessions. Revoke is useful after rotation, after a lost terminal, or when an agent run should stop receiving brokered access. hasp session grant plaintext Use this when a protected agent flow needs a short exception for secret reveal or secret copy. Plaintext grants should stay rare and short. They permit display or clipboard access. They do not change the vault item or repo binding. Runtime and vault state hasp daemon Use this to manage the local broker runtime. The daemon serves brokered requests for CLI, app, and agent flows. Normal commands start or reach it when needed. Use daemon commands when you need explicit control. hasp status Use this for a quick state readout. Status reports vault and daemon state. It does not run the same repair checks as doctor. hasp ping Use this to check daemon reachability. Ping is narrower than status and doctor. Use it in scripts that need to know whether the daemon answers. hasp vault Use hasp vault for local vault security operations. Vault commands affect local access material. They do not manage project bindings or app profiles. hasp vault lock Use this to lock local vault and session material. Lock is useful before you hand off a machine, pause work, or leave a shared terminal. hasp vault forget device Use this to remove device convenience material. Forget device is stronger than lock when local device trust should reset. You will need to unlock again through the normal path. hasp vault rekey Use this to change vault encryption credentials. Rekey protects local at rest material with new credentials. It does not rotate upstream API keys. Use hasp secret rotate for provider secret rotation. Audit and recovery hasp audit Use this to read the local audit log. Audit shows operations and access events without dumping managed values. Use filters when you need a narrower view. Use incident bundle for a redacted support or review artifact. Closest commands: hasp audit tail follows recent events. hasp doctor reports whether audit is degraded. hasp secret rotate and hasp session revoke are common follow ups after a leak. hasp audit tail Use this while you test setup, MCP, or app launchers. Tail prints recent events and can follow the log. hasp export backup Use this to write an encrypted backup of local HASP state. Backups protect against machine loss and bad local edits. Store the backup away from the repo and protect the backup passphrase. Production backups should be signed with the offline Ed25519 backup signer. Configure the daemon environment with HASP BACKUP SIGNING KEY B64 or HASP BACKUP SIGNING KEY HEX, and configure every restore environment with HASP BACKUP TRUST ROOTS HEX. When trust roots are set, unsigned backups and backups signed by unknown keys fail closed. Keep the private signer on offline media, publish only the public trust root, and rotate by distributing both old and new public keys during the transition window. hasp restore backup Use this to restore an encrypted backup. Restore writes local vault state from a backup. Inspect project bindings and active sessions after restore so stale local assumptions do not surprise you. Maintenance and reference hasp version Use this to print the build version. It helps compare CLI and daemon versions during support. hasp doctor also reports version mismatch. hasp completion Use this to generate shell completion scripts. Completion helps avoid typo driven failures and exposes nested subcommands in the shell. hasp upgrade Use this to install a signed newer release. Upgrade verifies the requested release path and refuses unsafe non interactive upgrades unless you pass the required confirmation flags. Closest commands: install scripts handle the first install. hasp version shows the current build. hasp doctor catches CLI and daemon version mismatch after upgrade. hasp docs Use this to render CLI help topics as Markdown. The generated file is useful for release artifacts, offline review, and docs drift checks. The generated reference preserves help text inside fenced code blocks. hasp tui Use hasp project status instead. hasp tui now prints a one shot project snapshot for compatibility. New docs and scripts should call the explicit project command. hasp internals help topic Use this when you are writing integrations or debugging lower level behavior. The internals topic explains broker vocabulary that normal first run docs avoid. hasp exit codes help topic Use this when a script needs stable error buckets. HASP emits structured JSON errors for JSON mode failures, with codes such as E USER INPUT, E PERMISSION, and E DAEMON UNREACHABLE.


================================================================================
Operate / Operator Guide
URL: https://gethasp.com/docs/v1.0.4/operator-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/operator-guide.md
--------------------------------------------------------------------------------

Operator guide Environment variables HASP HOME HASP MASTER PASSWORD HASP BACKUP PASSPHRASE Safe local workflow The preferred local path is: 1. import local material with hasp import 2. bind a repo with hasp bootstrap or hasp project bind 3. use hasp run or hasp mcp 4. use hasp inject for broker owned file materialization outside the repo 5. use hasp write env only when the convenience tradeoff is worth it Repo guardrails Install git hooks: Manual repo scan: Audited override: Release trust path Verify a packaged release before install: The packaged installer verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. The upgrade helper verifies the same release material and stages a new release tree before replacing the installed tree. Threat model limits HASP reduces accidental exposure and common local leaks on a normal developer machine. HASP does not provide strong same user local isolation. HASP does not defend against malicious same user local processes. pasted values and shell exports are still operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Operate / Repo targets
URL: https://gethasp.com/docs/v1.0.4/repo-targets/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/repo-targets.md
--------------------------------------------------------------------------------

Repo requirements and targets HASP can keep a value free repo contract in .hasp.manifest.json. Read Value free manifests first if you need the full contract. This page focuses on the commands you run after the manifest exists. The manifest answers two questions without storing secrets: what this repo needs which target should receive which subset A target is a named workflow inside a project, such as server.dev, server.integration, or release.sign. It is not authorization. Target expansion still goes through the normal project binding, grant, redaction, and audit checks. Manifest shape The file is committed. The values are not. Inspect requirements Use this when a teammate needs to know which local vault items to create: The output reports refs, kinds, target usage, and present/exposed state. It may suggest hasp secret add commands, but it does not create items, approve access, write value files, or run target commands. Inspect targets Target inspection omits command argv in agent facing MCP listing. Project doctor uses a dedicated safe JSON schema with diagnostic codes, refs, kinds, classifications, and booleans only. It flags unavailable target commands, stale examples, unignored generated outputs, workspace visible secret delivery, kind mismatches, and target drift without printing values or command argv. Generate examples Examples are placeholder files for framework compatibility: Generated examples contain placeholders such as HASP SECRET ; they never resolve vault values. HASP writes a marker into generated examples and refuses to overwrite stale hand authored files silently. Run a target run and inject reject extra env or file mappings when target is used. A target does not mean "all project secrets"; it expands only the delivery entries declared for that target. If a target has no command, pass an override command after . Write a generated value file write env target is convenience materialization. It writes a workspace visible file and requires explicit convenience approval. Prefer run or inject when the tool can receive env vars or broker owned temp files. Seed an app profile app connect target imports the target command and env/file mappings into a local app profile. The profile is local state; changing the manifest later does not silently rewrite the saved app profile. Drift review HASP stores a local review record for target expansion outside git. If a target later changes its command, refs, delivery set, or output paths, human CLI flows warn before continuing and hasp project doctor json reports target drift. Agent and MCP surface MCP target listing and explain are narrower than human CLI output. They return sanitized target names, descriptions, refs, delivery kinds, destination names, prerequisite status, and manifest identity. They do not return target command argv or secret values.


================================================================================
Operate / V1 production guide
URL: https://gethasp.com/docs/v1.0.4/v1-production-guide/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/v1-production-guide.md
--------------------------------------------------------------------------------

V1 production guide What V1 can prove today V1 is ready for a real developer machine pilot. You can test: local install on macOS or Linux local vault initialization import from .env and JSON credential files interactive hasp secret add connected app consumers through hasp app connect, run, install, shell, disconnect, and list connected agent consumers through hasp agent connect, disconnect, and list brokered run and safe inject explicit convenience write env repo guardrails, audit, and export backup/restore backup first class profile bootstrap for the shipped first class agent set generic broker compatibility for other CLI or MCP capable agents This guide is for one developer machine and one real repo. It is not a cloud rollout guide. Surface Today The current build supports both: consumer first setup through hasp secret add, hasp app ..., and hasp agent ... lower level broker primitives such as run, inject, and write env hasp setup no longer assumes you are here for an agent. You can use it for machine only setup, skip agent config for now, or continue into adding a vault secret and connecting one app in the same interactive flow. Installation path Use either: make build a published packaged release from GitHub Releases the optional https://downloads.gethasp.com/hasp/releases/ / mirror when that mirror is configured for the same release bytes Pilot checklist 1. Install from the release artifact, not only from source. 2. Initialize a fresh vault. 3. Import one .env file and one JSON credential file. 4. Bind one real repo. 5. Run one brokered command that needs a secret. 6. Write one convenience env file and confirm the warning path is clear. 7. Trigger check repo on a managed value inside the repo and confirm the default block. 8. Run hasp export backup to write an encrypted vault backup. 9. Run hasp restore backup into a second HASP home and confirm the restored vault opens. 10. Point one first class agent at hasp mcp. 11. Point one generic MCP capable client at the generic path. Known limits V1 is local first. There is no hosted control plane. V1 does not give you strong same user local isolation. V1 does not manage your PATH for you. app launchers still require explicit consent. In interactive hasp app connect, HASP asks before it creates one and, when needed, asks before it patches shell PATH. In scripts, use install=always never ask and add to path=always never ask (true/false are accepted as aliases for always/never). Launchers are written under HASP HOME/bin. V1 treats pasted values and shell exports as operator hygiene unless you route them through explicit import or capture paths.


================================================================================
Agents / Agent Profiles
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/README.md
--------------------------------------------------------------------------------

Agent Profiles These docs describe V1 agent profile tiers. Support Profile Contract A first class support profile is a shipped integration, not a config snippet. It is not first class until all of these exist: tested install and connection path recommended local configuration project binding recipe approval UX path safe inject path convenience write env path release gate regression coverage eval coverage for bootstrap and setup flows benchmark smoke coverage when the setup path changes Generic Broker Path HASP also ships a generic broker path for CLI or MCP capable agents that are not first class profiles yet. Use the generic path as the first proof surface when you need local first brokered access but do not want to claim agent specific approval UX or release gate coverage. If you need subprocess safe propagation, put hasp mcp behind the agent's wrapper or launcher path. Generic broker guide Profile Tiers Tier Meaning First class Shipped integration with docs, release gate regression coverage, eval coverage, and benchmark/smoke proof. Generic compatible Documented first proof broker path for agents that can invoke HASP MCP or CLI, but not enough external proof to claim first class support. Planned Named target without shipped operator contract. First Class Profiles Use hasp bootstrap profile project root as the compatibility bootstrap path before applying the agent specific config example from the matching profile doc. Bootstrap may create neutral repo aliases such as secret 01, but day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Agents should avoid raw reveal/get flows unless the operator explicitly needs plaintext. Connected agent configs also enable HASP agent safe mode by default when the agent is launched through a HASP wrapper or launcher. In a protected agent workflow, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Claude Code Cursor Aider Codex CLI OpenClaw Hermes Generic Compatible Profiles These profiles document a useful path, but they should not be described as first class until the proof contract above is satisfied with external usage evidence. generic compatible : first proof broker path for any CLI or MCP capable agent that is not a first class profile yet. Provides setup, doctor, and brokered proof commands without claiming agent specific approval UX or release gate coverage. See Generic broker guide. Update Rule When a profile changes, keep its quickstart steps, approval behavior, release gates, and benchmark/eval expectations in sync with the canonical V1 docs.


================================================================================
Agents / Codex CLI
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/codex-cli/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/codex-cli.md
--------------------------------------------------------------------------------

Codex CLI Config Surface Prefer the wrapper or launcher path for Codex style local agent workflows; use HASP as the generic stdio MCP server underneath it. Canonical command: hasp agent mcp codex cli Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile codex cli project root alias secret 01= 2. Verify the tool surface: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp codex cli 3. Register the MCP command in the Codex CLI config or launch wrapper you use locally. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp codex cli manages daemon backed sessions internally when no explicit token is supplied, and wrapper or launcher paths propagate the token into the whole process tree. Use manual hasp session open only for debugging or controlled reuse outside the default flow. Success Signal The tool surface lists hasp list, hasp run, hasp inject, hasp capture, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for env style command execution. Use hasp inject when the workflow needs a real file path outside the repo root. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Codex CLI setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Codex from hasp agent shell codex cli or hasp agent launch codex cli so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only for explicit repo visible materialization. Reuse depends on the same destination and the same canonical secret set. Alias names alone are not enough. Failure Recovery Restart hasp mcp if the stdio session stalls. Rebind the repo if the project root changed and the daemon reports a root mismatch. Known Caveats V1 uses local process tree protection to prevent accidental exposure, not malicious same user local processes.


================================================================================
Agents / Claude Code
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/claude-code/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/claude-code.md
--------------------------------------------------------------------------------

Claude Code Config Surface Prefer Claude Code's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp claude code Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile claude code project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp claude code 3. Add the MCP entry shown above to Claude Code, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but daily Claude Code usage should prefer the safe named ref form such as @OPENAI API KEY. HASP resolves that named ref back to the repo binding internally. Design direction: the target top level setup surface should be wrapper/launcher first, with hasp agent connect claude as the desired top level entry profile bootstrap remains the current compatibility path for the shipped V1 runtime Session Behavior hasp agent mcp claude code auto opens a daemon backed session for the bound project when the caller does not provide one, and the wrapper or launcher path propagates the session token to subprocesses. Use hasp session open only for debugging or when you intentionally want to inspect session state. Long Claude Code runs should use broker side window grants, not repeated manual prompts. Success Signal Claude Code lists hasp list, hasp run, hasp inject, hasp capture, hasp secret add, hasp secret update, hasp secret delete, hasp secret get, hasp secret expose, hasp secret hide, and hasp redact. hasp list returns only safe project scoped metadata, including neutral aliases and named refs. Safe Path Use hasp run for command execution. Use hasp inject for broker owned file materialization outside the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS when calling hasp run or hasp inject. Use hasp secret expose when the repo needs an existing personal vault secret. Use hasp secret add when the user wants the agent to store a new secret and keep working in the same chat flow. Connected Claude Code setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Claude Code from hasp agent shell claude code or hasp agent launch claude code so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env only when a repo visible env file is worth breaking the agent safe guarantee. Expect an explicit convenience approval and a warning when the destination is inside the bound project. Failure Recovery If tools fail with a session error, restart the MCP server or rerun the Claude Code command so HASP can open a fresh session. If tools fail with an approval error, grant the project or secret window inside HASP and retry. Known Caveats Raw write env output files are convenience materialization, not agent safe broker flow. Raw hasp secret get reveal is blocked inside protected agent workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. V1 uses daemon issued local sessions and local process tree protection, not strong same user local isolation.


================================================================================
Agents / Cursor
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/cursor/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/cursor.md
--------------------------------------------------------------------------------

Cursor Config Surface Prefer Cursor's wrapper or launcher path when available; use HASP as the stdio MCP server underneath it. Canonical command: hasp agent mcp cursor Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile cursor project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp cursor 3. Add the MCP entry shown above in Cursor, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp cursor auto opens a daemon backed session for Cursor if one is not supplied, and the wrapper or launcher path propagates the session token to subprocesses. Use window grants for longer Cursor loops instead of repeated per command prompts. Use hasp session open only for debugging or manual token inspection. Success Signal Cursor shows the HASP tool server as connected. hasp list returns only safe workspace metadata, including neutral aliases and named refs. Safe Path Use hasp run for brokered command execution. Use hasp inject when Cursor needs file based credentials without placing them in the repo. Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Cursor setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Cursor from hasp agent shell cursor or hasp agent launch cursor so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path Use hasp write env for .env.local style files only when convenience is worth the exposure. Reuse is limited to the same project, destination path, and canonical secret set. Failure Recovery Reconnect the MCP server if Cursor loses the HASP tool connection. Regrant the project or secret window when the daemon reports an approval failure. Known Caveats Broker managed deploy blocking only applies when you use HASP wrappers or installed hooks, which is the privacy preserving process tree boundary. Raw deploy commands outside HASP control remain warn only in V1.


================================================================================
Agents / Aider
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/aider/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/aider.md
--------------------------------------------------------------------------------

Aider Config Surface Prefer Aider's wrapper or launcher path when you need subprocess safe propagation; use HASP as the stdio MCP/tool process underneath it. Canonical command: hasp agent mcp aider Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile aider project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp aider 3. Point Aider at the stdio command shown above, or place that command behind the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior hasp agent mcp aider opens a fresh daemon backed session when Aider connects, and the wrapper or launcher path propagates that session into spawned subprocesses. Use broker side project and secret window grants for longer Aider sessions. Success Signal Aider can call hasp list and see only safe project scoped metadata, including neutral aliases and named refs. hasp run succeeds without returning raw managed values in output. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Aider setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Aider from hasp agent shell aider or hasp agent launch aider so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The user must approve convenience materialization explicitly for each destination/path scope. Failure Recovery Restart the HASP stdio server if Aider loses the connection. If capture fails, retry with explicit grant project and grant write inputs so the broker can audit the write. Known Caveats capture is a containment path for candidate secrets, not proof the value never touched the launched process tree beforehand.


================================================================================
Agents / Hermes
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/hermes/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/hermes.md
--------------------------------------------------------------------------------

Hermes Config Surface Prefer Hermes' wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp hermes Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile hermes project root alias secret 01= 2. Verify the broker locally: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp hermes 3. Register the command in Hermes' MCP or tool server configuration, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP creates a daemon backed session when Hermes starts the stdio server, and wrapper or launcher paths propagate that session into subprocesses. Keep long Hermes runs usable with project/secret window grants instead of repeated prompts. Success Signal Hermes lists only safe project scoped HASP metadata, including neutral aliases and named refs. hasp run and hasp inject succeed without exposing raw managed values back to the caller. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected Hermes setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching Hermes from hasp agent shell hermes or hasp agent launch hermes so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env The broker warns when the destination is inside the bound project and requires explicit convenience approval. Failure Recovery Restart the HASP stdio process if Hermes loses the MCP connection. If the daemon rejects a provided session token, let HASP open a fresh session instead of reusing the stale one. Known Caveats write env is intentionally outside the agent safe guarantee once the file exists in the project.


================================================================================
Agents / OpenClaw
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/openclaw/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/openclaw.md
--------------------------------------------------------------------------------

OpenClaw Config Surface Prefer OpenClaw's wrapper or launcher path when available; use HASP as the stdio MCP/tool server underneath it. Canonical command: hasp agent mcp openclaw Config Example Setup 1. Bootstrap the local profile: hasp bootstrap profile openclaw project root alias secret 01= 2. Verify the broker: printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' hasp agent mcp openclaw 3. Configure OpenClaw to invoke the HASP stdio command, or wire the same command into the wrapper or launcher path you already use. Bootstrap may create a neutral repo alias such as secret 01, but day to day usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Session Behavior HASP opens a daemon backed session when OpenClaw connects, and wrapper or launcher paths propagate that session into subprocesses. Use project and secret window grants for longer agent loops. Success Signal OpenClaw can list only safe workspace metadata, including neutral aliases and named refs. hasp inject returns file paths outside the repo root. Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. Connected OpenClaw setups enable HASP agent safe mode by default when launched through a HASP wrapper or launcher, so hasp secret get reveal and copy are blocked inside protected workflows unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, prefer launching OpenClaw from hasp agent shell openclaw or hasp agent launch openclaw so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree. Convenience Path hasp write env Convenience grants are explicit, audited, and tied to the same destination plus canonical secret identities. Failure Recovery If OpenClaw loses the tool connection, restart the HASP process and retry. If write env fails after alias remapping, request a new convenience approval for the new secret set. Known Caveats Broker managed repo protection covers installed hooks and HASP deploy wrappers, not arbitrary raw deploy commands.


================================================================================
Agents / Generic Broker Path
URL: https://gethasp.com/docs/v1.0.4/agent-profiles/generic/
Source: https://github.com/gethasp/hasp/blob/main/docs/agent-profiles/generic.md
--------------------------------------------------------------------------------

Generic Broker Path This is the first proof surface for CLI or MCP capable agents that are not first class HASP profiles yet. Use it to prove one real repo binding and one brokered success path without claiming agent specific approval UX, release gate coverage, or benchmark proof. When To Use This Path Use the generic broker path when an agent can speak stdio MCP or otherwise invoke hasp mcp, but does not have a first class HASP profile yet. This path keeps the local first broker model intact while giving you a clear first brokered proof before any profile specific support claim exists. Config Surface Canonical command: hasp mcp Generic local first setup: hasp setup agent generic compatible project root or hasp bootstrap generic project root Prefer the agent wrapper or launcher path when you need subprocess safe propagation. Setup Command Run this to initialize the vault, bind the repo, and wire the generic compatible MCP path in a single step: Or use the lower level bootstrap path directly: Doctor Command After setup, verify the generic compatible broker state with: or, using the bootstrap doctor subcommand with an explicit project root: First Brokered Proof Run this command to prove the local broker works end to end. It exits 0 only if the broker successfully injects the managed value into the subprocess environment: Replace @OPENAI API KEY with the named reference printed by setup. The exact command is also printed verbatim in the verification.brokered proof.command field of the hasp setup json output. Ready to Paste Config Snippets Use hasp bootstrap print config to get a ready to paste MCP config snippet for your agent: Each snippet embeds "support tier": "generic compatible" so the config is labeled as a generic broker path, not first class profile support. Config Example Setup 1. Initialize the local vault if needed: hasp init 2. Import any explicit local values you want to broker: hasp import .env 3. Bind the repo with hasp bootstrap generic project root and check the local generic compatible broker state with hasp bootstrap doctor generic project root 4. Wire the agent to hasp mcp using its stdio or MCP settings, or place that command behind the agent wrapper or launcher if you need subprocess coverage 5. Use hasp run, hasp inject, and hasp write env only when the workflow needs brokered access If bootstrap or binding creates a neutral repo alias such as secret 01, treat that as internal plumbing. Day to day agent usage should prefer safe named refs such as @OPENAI API KEY with hasp run or hasp inject. Success Signal hasp bootstrap doctor generic project root passes and confirms the local generic compatible broker state The agent can connect to hasp mcp hasp list returns only project scoped, brokered metadata, including neutral aliases and named refs One hasp run or hasp inject command completes against a named ref Brokered flows keep managed values out of agent context What This Does Not Prove first class support for the agent profile specific approval UX release gate coverage benchmark smoke coverage Safe Path hasp run hasp inject Prefer named refs such as @OPENAI API KEY or @GOOGLE APPLICATION CREDENTIALS in those tool calls instead of recalling secret 01. hasp write env only when explicit convenience materialization is acceptable When HASP is connected through the shipped agent wrapper or launcher path, agent safe mode is enabled by default. In protected workflows, hasp secret get reveal and copy are blocked unless the operator first grants one time plaintext access with hasp session grant plaintext. For stronger subprocess coverage, launch the agent through hasp agent launch or hasp agent shell so HASP AGENT SAFE MODE and HASP SESSION TOKEN reach the whole agent process tree instead of only the HASP MCP server. Known Limits This path does not imply first class support for the agent. V1 uses local, privacy preserving process tree protection to reduce accidental exposure on a normal developer machine. V1 does not defend against malicious same user local processes. Shell exports and pasted values remain operator hygiene risks unless they are routed through explicit import or brokered materialization.


================================================================================
Release / Changelog
URL: https://gethasp.com/docs/v1.0.4/changelog/
Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md
--------------------------------------------------------------------------------

Changelog All notable public releases should be summarized here. Unreleased [v1.0.4] Harden the private to public release driver so live verification waits for the Homebrew tap publish to land before fetching or installing from the tap. Add release publication regression coverage for the live verifier's Homebrew polling path. [v1.0.3] Fix the public Release workflow so pre publish release smoke no longer tries to install the Homebrew formula before the new artifacts are available on the R2 mirror. Keep Homebrew install verification after R2 publication and before Homebrew tap publication, then verify the published tap before creating the GitHub Release. [v1.0.2] Harden managed agent MCP startup so stale wrappers still answer the MCP initialize handshake instead of exiting when a saved agent record is missing. Make hasp setup agent persist the matching agent consumer record for every supported harness, including Codex CLI, Claude Code, Cursor, Aider, Hermes, and OpenClaw. Add regression coverage for every managed agent harness from setup through wrapper generation, persisted consumer state, and hasp agent mcp tools listing. [v1.0.1] Fix macOS setup convenience unlock so normal Keychain prompt latency does not get reported as an unavailable keychain. Fix hasp proof secret so project aliases such as secret 01 resolve correctly during brokered proof checks. Keep the public installer compatible with the published v1 release archive layout. [v1.0.0] Publish HASP v1 as the first public code and documentation line. Ship the local first runtime secret broker with encrypted vault storage, project scoped bindings, repo guardrails, protected agent process tree sessions, one time plaintext approval grants, brokered command execution, audited secret use, value free repo manifests, and first class agent profiles. Publish the release through the public Release workflow: supported platform tarballs, checksums, detached GPG signatures, packaged SBOM/provenance/status sidecars, Ed25519 upgrade signatures, Cloudflare R2 mirrors, download Worker metadata, Homebrew tap publication, and GitHub Release assets. Start public versioned documentation at /docs/v1.0.0/; the private source repository keeps pre v1 development history and archived release notes.


================================================================================
Release / Release distribution
URL: https://gethasp.com/docs/v1.0.4/release-distribution/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/release-distribution.md
--------------------------------------------------------------------------------

Release distribution This page covers the public release path for the curated HASP repository. What ships Public releases ship: versioned GitHub release assets optionally mirrored hosted artifacts backed by Cloudflare R2 when release mirror credentials are configured SHA256SUMS SHA256SUMS.asc detached signatures for the tarball and packaged binary packaged SBOM, provenance, code signing status, and reproducible build status files inside each tarball a public verification key a Homebrew formula pinned to the published artifact bytes Stable download contract GitHub Releases are the canonical public release asset location. When the R2 mirror is configured, the hosted release layout is https://downloads.gethasp.com/hasp/releases/ /. Each GitHub release and each mirrored release directory should include: hasp .tar.gz SHA256SUMS SHA256SUMS.asc hasp release public key.asc hasp .tar.gz.asc hasp bin.asc Formula/hasp.rb Each packaged tarball also contains: sbom.spdx.json slsa provenance.json CODE SIGNING STATUS.json REPRODUCIBLE BUILD.json Those files are package metadata sidecars, not external attestations from a remote CI system. On non macOS hosts, code signing status may report unsupported; when the slower reproducible build check is not enabled, REPRODUCIBLE BUILD.json may report not run. Verify and install The install helper verifies the signed checksum manifest, the tarball signature, and the packaged binary signature before it stages the install tree. Upgrade and uninstall The default uninstall path removes only the installed release tree. It does not remove HASP HOME or repo hooks unless the operator asks for that explicitly. Homebrew path The Homebrew formula must consume the published artifact bytes, not rebuild from the repository source tree. It should point at the canonical GitHub release asset URL unless the R2 mirror has been verified for the same byte set. Docs before tag Treat docs as part of the release payload. Before the tag is created, update the public docs for every command, package, install step, agent profile, error, or exposed behavior that changed. Maintainers then publish the matching versioned docs from the canonical release source. The release should not publish until /docs/ and /docs/vX.Y.Z/ match the binary and package that are going out. The public repository starts at v1.0.0. Keep pre v1 development history, snapshots, and release notes in the canonical source repository only. Operator note The local packaged lifecycle and the hosted publication flow are separate concerns: local scripts verify, install, upgrade, and uninstall the publication flow uploads the signed bytes and may mirror the same bytes to hosted URLs That separation is intentional. The local trust path must still work if the R2 hosted publication layer is unavailable.


================================================================================
Release / Install and release
URL: https://gethasp.com/docs/v1.0.4/install-and-release/
Source: https://github.com/gethasp/hasp/blob/main/public/docs/install-and-release.md
--------------------------------------------------------------------------------

Install and release This page covers the public install path and the release trust path together. Homebrew Use Homebrew for the normal public CLI install path: Use Install for Homebrew upgrade and uninstall commands. Hosted release layout GitHub Releases are the canonical hosted asset location. The optional R2 mirror, when configured for the same byte set,