# hasp full documentation bundle Version: 0.1.39 Docs root: https://gethasp.com/docs/ 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 first broker for managed secrets in agent workflows. It is built for people using coding agents on normal developer machines who need the agent to do useful work without turning .env files, copied tokens, and repo local credentials into the default operating model. What this public repo contains This repo contains the public code and release surface for: the Go broker and CLI under apps/server/ the public docs needed to build, test, verify, and install shipped releases This public repo is limited to the server/CLI release surface. Closed source apps, hosted services, marketing assets, and private planning docs stay outside this export. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports safe brokered execution through run, inject, and MCP flows provides audited convenience materialization when an operator explicitly asks for it installs repo guardrails so managed secrets do not get committed or deployed by accident The core rule is simple: In broker managed agent safe flows, managed secret values must not enter agent context. Start locally Source build: Packaged release: If you want the short path first, start with QUICKSTART.md. If you already installed HASP and want the step by step setup, start with After Install. Release model tagged releases publish signed release artifacts release assets can be mirrored to Cloudflare R2 behind a stable download host Homebrew support is artifact based, not source build based For the maintainer flow, see RELEASING.md. Public repo rule This repo is a curated public export of the canonical source tree. If maintainers accept a public PR, they replay the change through the canonical source tree and sync the public export back here before merging or tagging the release. Where to go next QUICKSTART.md docs/README.md SUPPORT.md SECURITY.md CONTRIBUTING.md ================================================================================ 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 / 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 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/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 If you already added the tap, brew install hasp is enough. After install, continue with After Install: 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 Generic compatible profiles are also available when they match your agent, but they are not first class support claims yet: 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=secret 01 Put the secret bound to secret 01 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 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. 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. 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 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. 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/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. ================================================================================ 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. 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 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. OpenClaw Hermes 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 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/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/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 / 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 repo 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 with the alias or named reference printed by setup (e.g. secret 01 or @OPENAI API KEY). 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/changelog/ Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md -------------------------------------------------------------------------------- Changelog All notable public releases should be summarized here. Unreleased [v0.1.37] Make the private markdown link checker portable across runner checkout roots so repo local absolute links created in one workspace are resolved against the current checkout during CI verification. [v0.1.36] Harden setup password handling around empty input, retry behavior, interrupt handling, and existing vault password prompts. Automate the Unix PTY Ctrl+C setup password smoke so interrupted setup stops before vault creation. Refresh logo concept assets used by the public brand surface. [v0.1.35] Ship value free repo requirements and target scoped delivery in .hasp.manifest.json: strict schema validation, safe project inspection, placeholder example generation, and project doctor diagnostics for stale examples, unavailable commands, unignored generated outputs, workspace visible secret delivery, kind mismatches, and manifest drift without exposing values or repo controlled command output. Add target expansion to hasp run, hasp inject, and hasp write env while preserving normal binding, grant, redaction, audit, and convenience materialization rules. Target expansion now records local review state and warns when command argv, refs, delivery sets, or output paths drift after review. Add target aware app and MCP surfaces: hasp app connect target, hasp targets, hasp target explain, and target aware MCP run/inject. Agent target listing and explain omit command argv and raw values. Update public docs and the docs site with repo target guidance, a regenerated CLI reference, and status/conformance entries for the shipped target manifest contract. [v0.1.34] Close the staff review hardening backlog before publication: strict doctor JSON allowlist enforcement, documented E error classification for plain CLI failures, read only doctor diagnostics by default, symlink safe write env, inherited backup passphrase stripping for brokered children, shared CLI/MCP repository scanning, capped MCP tool output, and narrower first screen CLI help. Downgrade release trust claims to match the real packaged artifacts: signatures still verify, while SBOM, provenance, code signing status, and reproducible build status are documented as local metadata sidecars rather than remote attestation. Add large vault, large output, MCP, and repo scan benchmark smoke coverage so future hardening work has performance evidence instead of relying on small fixtures. Fix the public release CI lane: add TestMain HASP HOME defaults to apps/server/cmd/hasp and apps/server/internal/runner so the paths.Resolve test isolation guard does not fire on packages that previously relied on a real /.hasp fallback. Make the canonical root cache invalidation test deterministic on Linux tmpfs by replacing RemoveAll+Mkdir (which can reuse the same inode immediately) with a sibling create plus rename, guaranteeing a distinct inode for os.SameFile. Stabilize two CI only flakes: poll for the daemon pid file (not just the socket) before StopDaemon in TestDaemonCommandStartBranch, and widen the GrantOnce TTL in TestEnforceSecretPlaintextPolicyConsumeFailure so the assertion remains focused on the persist failure path under heavy CI load. Fix a Linux only PTY drain race in executePTY where fast exit children like printf hello pty could lose their final bytes: wait for the master→stdout io.Copy goroutine to finish (slave close naturally surfaces buffered data plus EIO on the master) before force closing ptmx, with a 100ms timeout fallback so detached grandchildren that kept the slave fd open cannot stall the runner. Widen the four remaining 2 second daemon shutdown safety caps in test helpers (internal/mcp, internal/brokerops, internal/runtime, plus the second internal/app helper) to 10 seconds so a slow scheduler tick during the public release coverage lane no longer fails an otherwise clean test cleanup. Fix a daemon readiness race in the internal/evals integration helpers: after the v0.1.33 change that made hasp status connect only, the helpers were switched to hasp daemon start, but StartDaemon returns as soon as the broker is spawned (before the Unix socket is bound), so TestCLISessionLifecycleEval and TestStopEvalDaemonStopsDetachedDaemon could race the dial. Add a waitForEvalSocket poll (15s deadline, 25ms tick) immediately after each daemon start so dependent dials see a ready broker. Also add the grant window 15m flag to run, inject, capture, and write env invocations in TestCLIEndToEndMatrix, since the v0.1.33 hardening pass made an explicit window duration mandatory whenever any grant scope is window. [v0.1.33] Land the P0 security hardening pass: peer UID check on the daemon Unix socket, crash safe vault envelope writes, encoding aware byte range redactor, refusal of argv delivered plaintext in secret commands, write env clobber protection, scrubbing of inherited HASP env in spawned children, hardened git shell outs, per session inject directories, normalized vault unwrap errors, removal of the .test basename KDF weakening seam, and HMAC chained audit log entries under a per vault key. Migrate the vault KDF to argon2id with a backwards compatible read path, ship hasp vault rekdf to upgrade existing vaults in place, and add hasp vault forget device plus a wider hasp vault lock surface. Add operator facing CLI verbs: hasp secret show / reveal / copy, hasp secret search, hasp secret diff, hasp session list mine json, hasp audit tail [ n N] [ f], hasp completion , and inline TTY confirm for agent safe plaintext reveal/copy. Stabilize the user surface: enforce a strict json contract with structured error envelopes, introduce stable error codes and exit code buckets, standardise env NAME=@REF grammar across run / write env / app connect, replace tri state bool flags with always never ask, gate auto expose behind expose=ask always never, require explicit grant window when scope is window, accept duration shaped grant values, and deprecate hasp set / hasp capture / top level list+get shortcuts in favor of hasp secret. Polish the help and error surfaces: 'did you mean' suggestions for unknown topics and commands, distinct empty vault vs no match templates, populated Hint fields on key user facing errors, per command help bodies that list every FlagSet flag, dry run implies explain, ASCII glyph fallback under non UTF 8 locales, and an ambient json / quiet sweep across renderers. Improve daemon and broker robustness: bump daemon startup deadline to 15s, replace the os.Stat readiness check with net.Dial, memoize gitsafe.TopLevel and CanonicalProjectRoot.EvalSymlinks, surface randomHex entropy failures instead of panicking, detect pid reuse during session ResolveProcess, and parse global flags from any argv position. Continue the internal/app monolith split as foundation work: Stage 1 extracts leaf rendering primitives to internal/app/ui/, Stage 2 extracts five cycle relevant primitives to dedicated subpackages (internal/app/ttyutil/, internal/app/secrettypes/, internal/app/auditlog/, internal/app/vaultaccess/, internal/app/cmddispatch/) using a closure indirection pattern that keeps test seams in place with zero test file churn. Allocate a PTY when hasp run detects a TTY on stdout so child programs that probe for an interactive terminal keep working through the broker, and add ANSI aware streaming redaction so terminal control sequences no longer mask sensitive substrings. [v0.1.32] Close the post v0.1.31 V1 visibility remainder without widening the product: surface the stdin/shell export rescue path in hasp import help, write a paste rescue section plus V1 threat model limits and licensing and usage blocks into the packaged QUICKSTART.md, and align docs/quickstart.md with the same blocks. Reconcile the competitive baseline against shipped v0.1.31 behavior and drop outdated onboarding and generic compatible first proof notes from the public release story. Keep the Go verification bar at 100.0% statement coverage across all 13 packages. [v0.1.31] Finish V1 local first parity: complete the onboarding eval so hasp setup non interactive json bind imports reliably yields a ready brokered proof, and expose the generic compatible first proof surface through hasp agent list supported, hasp bootstrap print config, and the printed proof command. Restore 100.0% statement coverage across the Go modules and prune internal app drift, keeping the verification bar and maintenance boundaries intact as the product surface grows. [v0.1.30] Close the remaining V1 competitive gaps without widening the product: refresh the competitive baseline and matrix, restate the real V1 gaps, and add a single page visual competition matrix to the private docs. Reduce internal app drift by splitting the setup workflow into smaller maintenance boundaries. [v0.1.29] Close V1 conformance ahead of the release: finish scoped conformance work, retire completed roadmap review beads, and mark shipped versus future documentation status. Harden the agent safe broker spec after adversarial review so the brokered grant semantics stay enforced end to end under automated tests and production operator flows. [v0.1.28] Harden the agent safe path by switching generated agent configs to managed wrapper scripts, registering protected process trees with the runtime daemon, and resolving agent safe state from process ancestry before weaker env/repo fallbacks. Keep plaintext access inside agent safe sessions brokered through one time local approval grants, suppress native approval prompts under automated tests only, and preserve the production operator approval path. Raise and retain the Go verification bar at 100.0% coverage while splitting the agent setup, secret prompt/plaintext policy, and setup coverage hotspots into smaller maintenance boundaries. Fix single tarball verification for the public multi platform release manifest so operators can verify one downloaded tarball without also downloading every sibling platform archive. [v0.1.27] Stop temp home eval and release flows from leaving stray hasp daemon serve processes behind, and scope eval side CLI config writes to the test home instead of the real machine config. Harden the cleanup fallback so pidfile based teardown first verifies that the recorded PID still belongs to the expected scoped HASP daemon before it invokes daemon stop or sends kill signals. Raise the repo wide Go verification bar back to 100.0% coverage and split setup presentation helpers out of setup.go so the setup workflow and terminal rendering are no longer concentrated in one file. [v0.1.26] Harden macOS convenience unlock by targeting the explicit default keychain path for keychain set, get, and delete operations instead of relying on ambient search list behavior. Retry the setup time convenience unlock verification step before declaring it unavailable, and surface a concrete convenience unlock detail in setup output when macOS still blocks the keychain path. Keep the repo verification bar at 100.0% coverage and publish the patch through the signed release, R2 mirror, and Homebrew tap flow. [v0.1.25] Extend the launcher consent path so HASP can add its launcher directory to shell PATH, but only after the user says yes in interactive flows or passes add to path=true in scripts. Keep the new topic based help surface intact while covering the PATH edit code and rollback paths back to a deterministic 100.0% Go coverage gate. Publish the patch through the real HASP signing key, the GitHub release flow, and the configured R2 mirror. [v0.1.24] Add a real topic based CLI help surface under hasp help, hasp help ..., and command local help routes so users can learn the vault, app, agent, project, and broker concepts directly from the binary. Make launcher creation explicit in the app flow: interactive hasp app connect now asks before it writes a launcher, while scripted runs use install=true or install=false. Keep the repo coverage gate at 100.0%, keep conformance green, and publish the release with the real HASP signing key plus the configured R2 mirror path. [v0.1.23] Re cut the consumer first app and agent release with the real HASP release signing key so the published checksums, tarballs, and detached signatures no longer rely on ephemeral local signing. Keep the shipped hasp secret, hasp app, and hasp agent surfaces from v0.1.22 unchanged while publishing a clean signed patch release. [v0.1.22] Add the consumer first hasp app and hasp agent surfaces, including machine scoped app consumers, repo scoped agent connections, audited consumer profile storage, and runtime delivery for env vars, temporary files, and temporary dotenv bundles. Harden launcher ergonomics by validating app consumer names, forwarding runtime arguments through hasp app run, protecting unmanaged launcher paths from silent overwrite, and preserving rollback coverage for connect, install, and disconnect failure paths. Update the V1 and quickstart docs around the shipped consumer model while keeping the Go verification gate at 100.0% coverage and the full conformance lane green. [v0.1.21] Add the human first hasp secret CLI surface for add, update, delete, get, list, expose, and hide, plus matching MCP secret tools so coding agents can store and expose secrets without forcing the user out of chat. Tighten repo scoped secret enforcement so brokered execution no longer falls back to raw vault item names and automatic repo enablement only occurs for real git repositories. Raise the Go verification bar back to a deterministic 100.0% coverage gate, add direct branch coverage for the new secret flows, and harden local release signing scripts so ephemeral noninteractive signing works in release smoke and artifact evals. [v0.1.20] Negotiate the MCP protocol version during initialize so Claude accepts hasp mcp instead of rejecting the hard coded 2026 04 13 handshake. Keep compatibility with stricter clients by preferring the stable 2025 06 18 MCP protocol while still tolerating clients that explicitly request the newer version. [v0.1.19] Keep hasp setup responsive after password entry by time bounding the optional macOS convenience unlock enable and verification path instead of waiting on slow keychain failures. Skip macOS convenience unlock setup entirely when no usable default keychain exists, so setup falls back cleanly instead of surfacing the Keychain Not Found system dialog. [v0.1.18] Stop hasp mcp from replying to JSON RPC notifications, so Codex no longer fails MCP startup with Transport closed during the notifications/initialized handshake. Add regression coverage for the initialize plus notification handshake so future releases keep the MCP stream valid for stricter clients. [v0.1.17] Rework the interactive hasp setup confirmation and completion screens into grouped, aligned blocks so machine defaults, agent targets, statuses, and next steps are easier to scan at a glance. Add stronger TTY only color hierarchy for stage bullets, config paths, summary labels, statuses, and numbered next steps while keeping non TTY output clean and the 100.0% coverage gate intact. [v0.1.15] Support noninteractive GPG signing for public release packaging with HASP RELEASE GPG PASSPHRASE or HASP RELEASE GPG PASSPHRASE FILE, so passphrase protected release keys work in CI and scripted maintainer flows. Extend the release smoke lane to cover passphrase protected signing for both packaged release sidecars and assembled public release metadata, while keeping the public export verification lane green. [v0.1.14] Tighten the interactive hasp setup presentation so stage guidance uses cleaner bullets, TTY color accents, and a standalone success lead instead of the old indented summary line. Lock the setup output polish down with exact output regressions while keeping the absolute MCP command path fix and the 100.0% coverage gate intact. [v0.1.13] Write absolute hasp command paths into generated Codex and JSON MCP client configs so launcher environments do not depend on ambient PATH resolution. Keep the setup retry fix, convenience unlock compatibility fix, truthful version reporting, and 100.0% coverage gate intact. [v0.1.12] Store convenience unlock key material in a keychain compatible encoded form and decode it on readback, so macOS convenience unlock works reliably on real installed binaries. Keep the existing vault setup retry fix, truthful embedded version reporting, and 100.0% coverage gate intact. [v0.1.11] Embed the build version into HASP binaries so hasp version reports the binary’s own release identity instead of reading a nearby repo VERSION file from the current working directory. Keep the existing vault setup retry fix and 100.0% coverage gate intact while making stale installed binaries easier to detect. [v0.1.10] Re cut the setup retry fix release from a real PTY validated HEAD so the published version is unambiguous. Preserve the existing vault password retry behavior, convenience unlock verification, and the integration regressions added for both paths. [v0.1.9] Keep interactive hasp setup on the existing vault password prompt after a wrong password instead of aborting the whole flow. Add integration coverage for the exact retry path so future releases catch this regression automatically. [v0.1.8] Verify convenience unlock during hasp setup by reopening the vault through the keychain path before reporting success. Return a clearer CLI error when neither HASP MASTER PASSWORD nor convenience unlock is available for a vault opening command. Add integration coverage for the exact setup/status regression so future releases catch this mismatch automatically. [v0.1.7] Add hasp project adopt under [ preview] so operators can scan and enroll multiple local git repos using machine defaults without background crawling. Extend the CLI integration coverage and edge case tests for bulk adoption and password iteration selection, bringing the repo Go coverage gate back to 100.0%. Keep the curated public export boundary valid while landing the new V1 adoption path. [v0.1.6] Shift hasp setup to a machine wide onboarding model with defaults for automatic project adoption on first use. Auto create local project bindings from machine defaults when HASP is first used in a project, instead of requiring manual per repo setup. Keep repo scoped enforcement under the hood while removing the repo by repo onboarding tax. Maintain the corrected repo coverage gate at 100.0%. [v0.1.5] When interactive hasp setup master password confirmation does not match, setup now retries the password step in place instead of aborting the whole flow. Keep the retry path fully covered while preserving the corrected 100.0% repo coverage gate. [v0.1.4] Ignore saved setup defaults that point into ephemeral temp directories, so stale test or temp paths no longer show up as the default local HASP data directory. Tighten the hasp setup terminal layout with clearer visual stage separators and more compact guidance lines. Keep the redesigned setup flow fully covered and the corrected repo coverage gate at 100.0%. [v0.1.3] Replace the freeform interactive agent prompt in hasp setup with a numbered agent selection menu. Add a final review and confirm screen before hasp setup writes local vault, repo, or agent config changes. Keep interactive setup human readable while preserving json and non interactive automation paths. Maintain a stable default go test ./... path and a corrected 100.0% coverage gate after the setup redesign. [v0.1.2] Redesign hasp setup into a more contextual staged onboarding flow with clearer machine, repo, and agent guidance. Stop stale saved setup paths from surfacing dead temp directories as the default local HASP data path. Keep interactive setup human readable while preserving json and non interactive machine output for automation. Stabilize the default parallel Go test path while keeping the corrected coverage gate at 100.0%. [v0.1.1] Add the new hasp setup flow for first run machine, repo, and agent MCP configuration. Expand bootstrap, doctor, and operator guidance so local install and setup are easier to verify end to end. Harden the packaged release lifecycle with verify, install, upgrade, uninstall, hosted artifact publication, and Homebrew tap updates. Improve test and coverage rigor, including deterministic 100.0% coverage and a stable default go test ./... path in test binaries. [v0.1.0] Initial public export and release publication lane setup. Public release workflow for GitHub Releases, Cloudflare R2 mirroring, and Homebrew tap publication. Signed packaged releases with verification material and artifact pinned formula generation. ================================================================================ 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 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 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. 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 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. Publish the matching versioned docs from the canonical release source. The public /docs/ route and the release route /docs/vX.Y.Z/ must describe the tag that is about to be published. 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: 0.1.37 (unknown) 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 vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit 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 . 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/v0.1.37/overview/ Source: https://github.com/gethasp/hasp/blob/main/public/README.md -------------------------------------------------------------------------------- HASP HASP is a local first broker for managed secrets in agent workflows. It is built for people using coding agents on normal developer machines who need the agent to do useful work without turning .env files, copied tokens, and repo local credentials into the default operating model. What this public repo contains This repo contains the public code and release surface for: the Go broker and CLI under apps/server/ the public docs needed to build, test, verify, and install shipped releases This public repo is limited to the server/CLI release surface. Closed source apps, hosted services, marketing assets, and private planning docs stay outside this export. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports safe brokered execution through run, inject, and MCP flows provides audited convenience materialization when an operator explicitly asks for it installs repo guardrails so managed secrets do not get committed or deployed by accident The core rule is simple: In broker managed agent safe flows, managed secret values must not enter agent context. Start locally Source build: Packaged release: If you want the short path first, start with QUICKSTART.md. If you already installed HASP and want the step by step setup, start with After Install. Release model tagged releases publish signed release artifacts release assets can be mirrored to Cloudflare R2 behind a stable download host Homebrew support is artifact based, not source build based For the maintainer flow, see RELEASING.md. Public repo rule This repo is a curated public export of the canonical source tree. If maintainers accept a public PR, they replay the change through the canonical source tree and sync the public export back here before merging or tagging the release. Where to go next QUICKSTART.md docs/README.md SUPPORT.md SECURITY.md CONTRIBUTING.md ================================================================================ Start / Quickstart URL: https://gethasp.com/docs/v0.1.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/v0.1.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 / Value-free manifests URL: https://gethasp.com/docs/v0.1.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 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/v0.1.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 If you already added the tap, brew install hasp is enough. After install, continue with After Install: 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/v0.1.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 Generic compatible profiles are also available when they match your agent, but they are not first class support claims yet: 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=secret 01 Put the secret bound to secret 01 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/v0.1.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 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. 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. 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/v0.1.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 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. 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/v0.1.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. ================================================================================ Agents / Agent Profiles URL: https://gethasp.com/docs/v0.1.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. 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 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. OpenClaw Hermes 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/v0.1.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 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/v0.1.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 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/v0.1.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/v0.1.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/v0.1.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 / OpenClaw URL: https://gethasp.com/docs/v0.1.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/v0.1.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 repo 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 with the alias or named reference printed by setup (e.g. secret 01 or @OPENAI API KEY). 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/v0.1.37/changelog/ Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md -------------------------------------------------------------------------------- Changelog All notable public releases should be summarized here. Unreleased [v0.1.37] Make the private markdown link checker portable across runner checkout roots so repo local absolute links created in one workspace are resolved against the current checkout during CI verification. [v0.1.36] Harden setup password handling around empty input, retry behavior, interrupt handling, and existing vault password prompts. Automate the Unix PTY Ctrl+C setup password smoke so interrupted setup stops before vault creation. Refresh logo concept assets used by the public brand surface. [v0.1.35] Ship value free repo requirements and target scoped delivery in .hasp.manifest.json: strict schema validation, safe project inspection, placeholder example generation, and project doctor diagnostics for stale examples, unavailable commands, unignored generated outputs, workspace visible secret delivery, kind mismatches, and manifest drift without exposing values or repo controlled command output. Add target expansion to hasp run, hasp inject, and hasp write env while preserving normal binding, grant, redaction, audit, and convenience materialization rules. Target expansion now records local review state and warns when command argv, refs, delivery sets, or output paths drift after review. Add target aware app and MCP surfaces: hasp app connect target, hasp targets, hasp target explain, and target aware MCP run/inject. Agent target listing and explain omit command argv and raw values. Update public docs and the docs site with repo target guidance, a regenerated CLI reference, and status/conformance entries for the shipped target manifest contract. [v0.1.34] Close the staff review hardening backlog before publication: strict doctor JSON allowlist enforcement, documented E error classification for plain CLI failures, read only doctor diagnostics by default, symlink safe write env, inherited backup passphrase stripping for brokered children, shared CLI/MCP repository scanning, capped MCP tool output, and narrower first screen CLI help. Downgrade release trust claims to match the real packaged artifacts: signatures still verify, while SBOM, provenance, code signing status, and reproducible build status are documented as local metadata sidecars rather than remote attestation. Add large vault, large output, MCP, and repo scan benchmark smoke coverage so future hardening work has performance evidence instead of relying on small fixtures. Fix the public release CI lane: add TestMain HASP HOME defaults to apps/server/cmd/hasp and apps/server/internal/runner so the paths.Resolve test isolation guard does not fire on packages that previously relied on a real /.hasp fallback. Make the canonical root cache invalidation test deterministic on Linux tmpfs by replacing RemoveAll+Mkdir (which can reuse the same inode immediately) with a sibling create plus rename, guaranteeing a distinct inode for os.SameFile. Stabilize two CI only flakes: poll for the daemon pid file (not just the socket) before StopDaemon in TestDaemonCommandStartBranch, and widen the GrantOnce TTL in TestEnforceSecretPlaintextPolicyConsumeFailure so the assertion remains focused on the persist failure path under heavy CI load. Fix a Linux only PTY drain race in executePTY where fast exit children like printf hello pty could lose their final bytes: wait for the master→stdout io.Copy goroutine to finish (slave close naturally surfaces buffered data plus EIO on the master) before force closing ptmx, with a 100ms timeout fallback so detached grandchildren that kept the slave fd open cannot stall the runner. Widen the four remaining 2 second daemon shutdown safety caps in test helpers (internal/mcp, internal/brokerops, internal/runtime, plus the second internal/app helper) to 10 seconds so a slow scheduler tick during the public release coverage lane no longer fails an otherwise clean test cleanup. Fix a daemon readiness race in the internal/evals integration helpers: after the v0.1.33 change that made hasp status connect only, the helpers were switched to hasp daemon start, but StartDaemon returns as soon as the broker is spawned (before the Unix socket is bound), so TestCLISessionLifecycleEval and TestStopEvalDaemonStopsDetachedDaemon could race the dial. Add a waitForEvalSocket poll (15s deadline, 25ms tick) immediately after each daemon start so dependent dials see a ready broker. Also add the grant window 15m flag to run, inject, capture, and write env invocations in TestCLIEndToEndMatrix, since the v0.1.33 hardening pass made an explicit window duration mandatory whenever any grant scope is window. [v0.1.33] Land the P0 security hardening pass: peer UID check on the daemon Unix socket, crash safe vault envelope writes, encoding aware byte range redactor, refusal of argv delivered plaintext in secret commands, write env clobber protection, scrubbing of inherited HASP env in spawned children, hardened git shell outs, per session inject directories, normalized vault unwrap errors, removal of the .test basename KDF weakening seam, and HMAC chained audit log entries under a per vault key. Migrate the vault KDF to argon2id with a backwards compatible read path, ship hasp vault rekdf to upgrade existing vaults in place, and add hasp vault forget device plus a wider hasp vault lock surface. Add operator facing CLI verbs: hasp secret show / reveal / copy, hasp secret search, hasp secret diff, hasp session list mine json, hasp audit tail [ n N] [ f], hasp completion , and inline TTY confirm for agent safe plaintext reveal/copy. Stabilize the user surface: enforce a strict json contract with structured error envelopes, introduce stable error codes and exit code buckets, standardise env NAME=@REF grammar across run / write env / app connect, replace tri state bool flags with always never ask, gate auto expose behind expose=ask always never, require explicit grant window when scope is window, accept duration shaped grant values, and deprecate hasp set / hasp capture / top level list+get shortcuts in favor of hasp secret. Polish the help and error surfaces: 'did you mean' suggestions for unknown topics and commands, distinct empty vault vs no match templates, populated Hint fields on key user facing errors, per command help bodies that list every FlagSet flag, dry run implies explain, ASCII glyph fallback under non UTF 8 locales, and an ambient json / quiet sweep across renderers. Improve daemon and broker robustness: bump daemon startup deadline to 15s, replace the os.Stat readiness check with net.Dial, memoize gitsafe.TopLevel and CanonicalProjectRoot.EvalSymlinks, surface randomHex entropy failures instead of panicking, detect pid reuse during session ResolveProcess, and parse global flags from any argv position. Continue the internal/app monolith split as foundation work: Stage 1 extracts leaf rendering primitives to internal/app/ui/, Stage 2 extracts five cycle relevant primitives to dedicated subpackages (internal/app/ttyutil/, internal/app/secrettypes/, internal/app/auditlog/, internal/app/vaultaccess/, internal/app/cmddispatch/) using a closure indirection pattern that keeps test seams in place with zero test file churn. Allocate a PTY when hasp run detects a TTY on stdout so child programs that probe for an interactive terminal keep working through the broker, and add ANSI aware streaming redaction so terminal control sequences no longer mask sensitive substrings. [v0.1.32] Close the post v0.1.31 V1 visibility remainder without widening the product: surface the stdin/shell export rescue path in hasp import help, write a paste rescue section plus V1 threat model limits and licensing and usage blocks into the packaged QUICKSTART.md, and align docs/quickstart.md with the same blocks. Reconcile the competitive baseline against shipped v0.1.31 behavior and drop outdated onboarding and generic compatible first proof notes from the public release story. Keep the Go verification bar at 100.0% statement coverage across all 13 packages. [v0.1.31] Finish V1 local first parity: complete the onboarding eval so hasp setup non interactive json bind imports reliably yields a ready brokered proof, and expose the generic compatible first proof surface through hasp agent list supported, hasp bootstrap print config, and the printed proof command. Restore 100.0% statement coverage across the Go modules and prune internal app drift, keeping the verification bar and maintenance boundaries intact as the product surface grows. [v0.1.30] Close the remaining V1 competitive gaps without widening the product: refresh the competitive baseline and matrix, restate the real V1 gaps, and add a single page visual competition matrix to the private docs. Reduce internal app drift by splitting the setup workflow into smaller maintenance boundaries. [v0.1.29] Close V1 conformance ahead of the release: finish scoped conformance work, retire completed roadmap review beads, and mark shipped versus future documentation status. Harden the agent safe broker spec after adversarial review so the brokered grant semantics stay enforced end to end under automated tests and production operator flows. [v0.1.28] Harden the agent safe path by switching generated agent configs to managed wrapper scripts, registering protected process trees with the runtime daemon, and resolving agent safe state from process ancestry before weaker env/repo fallbacks. Keep plaintext access inside agent safe sessions brokered through one time local approval grants, suppress native approval prompts under automated tests only, and preserve the production operator approval path. Raise and retain the Go verification bar at 100.0% coverage while splitting the agent setup, secret prompt/plaintext policy, and setup coverage hotspots into smaller maintenance boundaries. Fix single tarball verification for the public multi platform release manifest so operators can verify one downloaded tarball without also downloading every sibling platform archive. [v0.1.27] Stop temp home eval and release flows from leaving stray hasp daemon serve processes behind, and scope eval side CLI config writes to the test home instead of the real machine config. Harden the cleanup fallback so pidfile based teardown first verifies that the recorded PID still belongs to the expected scoped HASP daemon before it invokes daemon stop or sends kill signals. Raise the repo wide Go verification bar back to 100.0% coverage and split setup presentation helpers out of setup.go so the setup workflow and terminal rendering are no longer concentrated in one file. [v0.1.26] Harden macOS convenience unlock by targeting the explicit default keychain path for keychain set, get, and delete operations instead of relying on ambient search list behavior. Retry the setup time convenience unlock verification step before declaring it unavailable, and surface a concrete convenience unlock detail in setup output when macOS still blocks the keychain path. Keep the repo verification bar at 100.0% coverage and publish the patch through the signed release, R2 mirror, and Homebrew tap flow. [v0.1.25] Extend the launcher consent path so HASP can add its launcher directory to shell PATH, but only after the user says yes in interactive flows or passes add to path=true in scripts. Keep the new topic based help surface intact while covering the PATH edit code and rollback paths back to a deterministic 100.0% Go coverage gate. Publish the patch through the real HASP signing key, the GitHub release flow, and the configured R2 mirror. [v0.1.24] Add a real topic based CLI help surface under hasp help, hasp help ..., and command local help routes so users can learn the vault, app, agent, project, and broker concepts directly from the binary. Make launcher creation explicit in the app flow: interactive hasp app connect now asks before it writes a launcher, while scripted runs use install=true or install=false. Keep the repo coverage gate at 100.0%, keep conformance green, and publish the release with the real HASP signing key plus the configured R2 mirror path. [v0.1.23] Re cut the consumer first app and agent release with the real HASP release signing key so the published checksums, tarballs, and detached signatures no longer rely on ephemeral local signing. Keep the shipped hasp secret, hasp app, and hasp agent surfaces from v0.1.22 unchanged while publishing a clean signed patch release. [v0.1.22] Add the consumer first hasp app and hasp agent surfaces, including machine scoped app consumers, repo scoped agent connections, audited consumer profile storage, and runtime delivery for env vars, temporary files, and temporary dotenv bundles. Harden launcher ergonomics by validating app consumer names, forwarding runtime arguments through hasp app run, protecting unmanaged launcher paths from silent overwrite, and preserving rollback coverage for connect, install, and disconnect failure paths. Update the V1 and quickstart docs around the shipped consumer model while keeping the Go verification gate at 100.0% coverage and the full conformance lane green. [v0.1.21] Add the human first hasp secret CLI surface for add, update, delete, get, list, expose, and hide, plus matching MCP secret tools so coding agents can store and expose secrets without forcing the user out of chat. Tighten repo scoped secret enforcement so brokered execution no longer falls back to raw vault item names and automatic repo enablement only occurs for real git repositories. Raise the Go verification bar back to a deterministic 100.0% coverage gate, add direct branch coverage for the new secret flows, and harden local release signing scripts so ephemeral noninteractive signing works in release smoke and artifact evals. [v0.1.20] Negotiate the MCP protocol version during initialize so Claude accepts hasp mcp instead of rejecting the hard coded 2026 04 13 handshake. Keep compatibility with stricter clients by preferring the stable 2025 06 18 MCP protocol while still tolerating clients that explicitly request the newer version. [v0.1.19] Keep hasp setup responsive after password entry by time bounding the optional macOS convenience unlock enable and verification path instead of waiting on slow keychain failures. Skip macOS convenience unlock setup entirely when no usable default keychain exists, so setup falls back cleanly instead of surfacing the Keychain Not Found system dialog. [v0.1.18] Stop hasp mcp from replying to JSON RPC notifications, so Codex no longer fails MCP startup with Transport closed during the notifications/initialized handshake. Add regression coverage for the initialize plus notification handshake so future releases keep the MCP stream valid for stricter clients. [v0.1.17] Rework the interactive hasp setup confirmation and completion screens into grouped, aligned blocks so machine defaults, agent targets, statuses, and next steps are easier to scan at a glance. Add stronger TTY only color hierarchy for stage bullets, config paths, summary labels, statuses, and numbered next steps while keeping non TTY output clean and the 100.0% coverage gate intact. [v0.1.15] Support noninteractive GPG signing for public release packaging with HASP RELEASE GPG PASSPHRASE or HASP RELEASE GPG PASSPHRASE FILE, so passphrase protected release keys work in CI and scripted maintainer flows. Extend the release smoke lane to cover passphrase protected signing for both packaged release sidecars and assembled public release metadata, while keeping the public export verification lane green. [v0.1.14] Tighten the interactive hasp setup presentation so stage guidance uses cleaner bullets, TTY color accents, and a standalone success lead instead of the old indented summary line. Lock the setup output polish down with exact output regressions while keeping the absolute MCP command path fix and the 100.0% coverage gate intact. [v0.1.13] Write absolute hasp command paths into generated Codex and JSON MCP client configs so launcher environments do not depend on ambient PATH resolution. Keep the setup retry fix, convenience unlock compatibility fix, truthful version reporting, and 100.0% coverage gate intact. [v0.1.12] Store convenience unlock key material in a keychain compatible encoded form and decode it on readback, so macOS convenience unlock works reliably on real installed binaries. Keep the existing vault setup retry fix, truthful embedded version reporting, and 100.0% coverage gate intact. [v0.1.11] Embed the build version into HASP binaries so hasp version reports the binary’s own release identity instead of reading a nearby repo VERSION file from the current working directory. Keep the existing vault setup retry fix and 100.0% coverage gate intact while making stale installed binaries easier to detect. [v0.1.10] Re cut the setup retry fix release from a real PTY validated HEAD so the published version is unambiguous. Preserve the existing vault password retry behavior, convenience unlock verification, and the integration regressions added for both paths. [v0.1.9] Keep interactive hasp setup on the existing vault password prompt after a wrong password instead of aborting the whole flow. Add integration coverage for the exact retry path so future releases catch this regression automatically. [v0.1.8] Verify convenience unlock during hasp setup by reopening the vault through the keychain path before reporting success. Return a clearer CLI error when neither HASP MASTER PASSWORD nor convenience unlock is available for a vault opening command. Add integration coverage for the exact setup/status regression so future releases catch this mismatch automatically. [v0.1.7] Add hasp project adopt under [ preview] so operators can scan and enroll multiple local git repos using machine defaults without background crawling. Extend the CLI integration coverage and edge case tests for bulk adoption and password iteration selection, bringing the repo Go coverage gate back to 100.0%. Keep the curated public export boundary valid while landing the new V1 adoption path. [v0.1.6] Shift hasp setup to a machine wide onboarding model with defaults for automatic project adoption on first use. Auto create local project bindings from machine defaults when HASP is first used in a project, instead of requiring manual per repo setup. Keep repo scoped enforcement under the hood while removing the repo by repo onboarding tax. Maintain the corrected repo coverage gate at 100.0%. [v0.1.5] When interactive hasp setup master password confirmation does not match, setup now retries the password step in place instead of aborting the whole flow. Keep the retry path fully covered while preserving the corrected 100.0% repo coverage gate. [v0.1.4] Ignore saved setup defaults that point into ephemeral temp directories, so stale test or temp paths no longer show up as the default local HASP data directory. Tighten the hasp setup terminal layout with clearer visual stage separators and more compact guidance lines. Keep the redesigned setup flow fully covered and the corrected repo coverage gate at 100.0%. [v0.1.3] Replace the freeform interactive agent prompt in hasp setup with a numbered agent selection menu. Add a final review and confirm screen before hasp setup writes local vault, repo, or agent config changes. Keep interactive setup human readable while preserving json and non interactive automation paths. Maintain a stable default go test ./... path and a corrected 100.0% coverage gate after the setup redesign. [v0.1.2] Redesign hasp setup into a more contextual staged onboarding flow with clearer machine, repo, and agent guidance. Stop stale saved setup paths from surfacing dead temp directories as the default local HASP data path. Keep interactive setup human readable while preserving json and non interactive machine output for automation. Stabilize the default parallel Go test path while keeping the corrected coverage gate at 100.0%. [v0.1.1] Add the new hasp setup flow for first run machine, repo, and agent MCP configuration. Expand bootstrap, doctor, and operator guidance so local install and setup are easier to verify end to end. Harden the packaged release lifecycle with verify, install, upgrade, uninstall, hosted artifact publication, and Homebrew tap updates. Improve test and coverage rigor, including deterministic 100.0% coverage and a stable default go test ./... path in test binaries. [v0.1.0] Initial public export and release publication lane setup. Public release workflow for GitHub Releases, Cloudflare R2 mirroring, and Homebrew tap publication. Signed packaged releases with verification material and artifact pinned formula generation. ================================================================================ Release / Release distribution URL: https://gethasp.com/docs/v0.1.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 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 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. 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/v0.1.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 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. Publish the matching versioned docs from the canonical release source. The public /docs/ route and the release route /docs/vX.Y.Z/ must describe the tag that is about to be published. 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/v0.1.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/v0.1.37/cli-reference/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md -------------------------------------------------------------------------------- HASP CLI reference Build: 0.1.37 (unknown) 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 vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes ================================================================================ Reference / Errors URL: https://gethasp.com/docs/v0.1.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 . 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/v0.1.36/overview/ Source: https://github.com/gethasp/hasp/blob/main/public/README.md -------------------------------------------------------------------------------- HASP HASP is a local first broker for managed secrets in agent workflows. It is built for people using coding agents on normal developer machines who need the agent to do useful work without turning .env files, copied tokens, and repo local credentials into the default operating model. What this public repo contains This repo contains the public code and release surface for: the Go broker and CLI under apps/server/ the public docs needed to build, test, verify, and install shipped releases This public repo is limited to the server/CLI release surface. Closed source apps, hosted services, marketing assets, and private planning docs stay outside this export. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports safe brokered execution through run, inject, and MCP flows provides audited convenience materialization when an operator explicitly asks for it installs repo guardrails so managed secrets do not get committed or deployed by accident The core rule is simple: In broker managed agent safe flows, managed secret values must not enter agent context. Start locally Source build: Packaged release: If you want the short path first, start with QUICKSTART.md. If you already installed HASP with Homebrew and want the step by step setup, start with docs/after homebrew.md. Release model tagged releases publish signed release artifacts release assets can be mirrored to Cloudflare R2 behind a stable download host Homebrew support is artifact based, not source build based For the maintainer flow, see RELEASING.md. Public repo rule This repo is a curated public export of the canonical source tree. If maintainers accept a public PR, they replay the change through the canonical source tree and sync the public export back here before merging or tagging the release. Where to go next QUICKSTART.md docs/README.md SUPPORT.md SECURITY.md CONTRIBUTING.md ================================================================================ Start / Quickstart URL: https://gethasp.com/docs/v0.1.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 with Homebrew and want the full beginner flow, read docs/after homebrew.md. 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/v0.1.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, build.config, 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. 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 / After Homebrew URL: https://gethasp.com/docs/v0.1.36/after-homebrew/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md -------------------------------------------------------------------------------- I installed HASP with Homebrew. Now what? This guide is for the most common starting point: you already ran brew tap gethasp/homebrew tap you already ran brew install 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 Homebrew. It can: 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 is the manual flow and troubleshooting fallback. The normal path is guided The Homebrew 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 common day to day surface should look like: hasp secret add hasp app connect hasp agent connect not repeated command wrapping or repeated repo/bootstrap thinking. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. 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 Homebrew'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 actually 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 Generic compatible profiles are also available when they match your agent, but they are not first class support claims yet: 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=secret 01 Put the secret bound to secret 01 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 actually do day to day You usually need only three commands. A. Run a command with a secret Use this whenever you can. B. Materialize a file only when you really need to Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. C. Check what HASP has been doing Use that if you want to review imports, approvals, backup/restore events, and similar actions. 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 you write a real file, that file is truly real: 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 If you want the absolute minimum happy path, this is it: If those commands work, you are ready to connect your coding agent. ================================================================================ Start / Install URL: https://gethasp.com/docs/v0.1.36/install/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md -------------------------------------------------------------------------------- Install HASP Source build Packaged release Default install prefix: Installed binary: Upgrade Uninstall The default uninstall path removes the installed release tree only. ================================================================================ Operate / Command guide URL: https://gethasp.com/docs/v0.1.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 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 or Secrets.example.xcconfig. 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 such as a macOS xcconfig file, 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. 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. 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/v0.1.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 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. 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/v0.1.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. 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, build.config, 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. ================================================================================ Agents / Agent Profiles URL: https://gethasp.com/docs/v0.1.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. 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 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. OpenClaw Hermes 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/v0.1.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 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 plus the same canonical secret set, not just alias names. 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/v0.1.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 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/v0.1.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/v0.1.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/v0.1.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 / OpenClaw URL: https://gethasp.com/docs/v0.1.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/v0.1.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 repo 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 with the alias or named reference printed by setup (e.g. secret 01 or @OPENAI API KEY). 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 clearly 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/v0.1.36/changelog/ Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md -------------------------------------------------------------------------------- Changelog All notable public releases should be summarized here. Unreleased [v0.1.36] Harden setup password handling around empty input, retry behavior, interrupt handling, and existing vault password prompts. Automate the Unix PTY Ctrl+C setup password smoke so interrupted setup stops before vault creation. Refresh logo concept assets used by the public brand surface. [v0.1.35] Ship value free repo requirements and target scoped delivery in .hasp.manifest.json: strict schema validation, safe project inspection, placeholder example generation, and project doctor diagnostics for stale examples, unavailable commands, unignored generated outputs, workspace visible secret delivery, kind mismatches, and manifest drift without exposing values or repo controlled command output. Add target expansion to hasp run, hasp inject, and hasp write env while preserving normal binding, grant, redaction, audit, and convenience materialization rules. Target expansion now records local review state and warns when command argv, refs, delivery sets, or output paths drift after review. Add target aware app and MCP surfaces: hasp app connect target, hasp targets, hasp target explain, and target aware MCP run/inject. Agent target listing and explain omit command argv and raw values. Update public docs and the docs site with repo target guidance, a regenerated CLI reference, and status/conformance entries for the shipped target manifest contract. [v0.1.34] Close the staff review hardening backlog before publication: strict doctor JSON allowlist enforcement, documented E error classification for plain CLI failures, read only doctor diagnostics by default, symlink safe write env, inherited backup passphrase stripping for brokered children, shared CLI/MCP repository scanning, capped MCP tool output, and narrower first screen CLI help. Downgrade release trust claims to match the real packaged artifacts: signatures still verify, while SBOM, provenance, code signing status, and reproducible build status are documented as local metadata sidecars rather than remote attestation. Add large vault, large output, MCP, and repo scan benchmark smoke coverage so future hardening work has performance evidence instead of relying on small fixtures. Fix the public release CI lane: add TestMain HASP HOME defaults to apps/server/cmd/hasp and apps/server/internal/runner so the paths.Resolve test isolation guard does not fire on packages that previously relied on a real /.hasp fallback. Make the canonical root cache invalidation test deterministic on Linux tmpfs by replacing RemoveAll+Mkdir (which can reuse the same inode immediately) with a sibling create plus rename, guaranteeing a distinct inode for os.SameFile. Stabilize two CI only flakes: poll for the daemon pid file (not just the socket) before StopDaemon in TestDaemonCommandStartBranch, and widen the GrantOnce TTL in TestEnforceSecretPlaintextPolicyConsumeFailure so the assertion remains focused on the persist failure path under heavy CI load. Fix a Linux only PTY drain race in executePTY where fast exit children like printf hello pty could lose their final bytes: wait for the master→stdout io.Copy goroutine to finish (slave close naturally surfaces buffered data plus EIO on the master) before force closing ptmx, with a 100ms timeout fallback so detached grandchildren that kept the slave fd open cannot stall the runner. Widen the four remaining 2 second daemon shutdown safety caps in test helpers (internal/mcp, internal/brokerops, internal/runtime, plus the second internal/app helper) to 10 seconds so a slow scheduler tick during the public release coverage lane no longer fails an otherwise clean test cleanup. Fix a daemon readiness race in the internal/evals integration helpers: after the v0.1.33 change that made hasp status connect only, the helpers were switched to hasp daemon start, but StartDaemon returns as soon as the broker is spawned (before the Unix socket is bound), so TestCLISessionLifecycleEval and TestStopEvalDaemonStopsDetachedDaemon could race the dial. Add a waitForEvalSocket poll (15s deadline, 25ms tick) immediately after each daemon start so dependent dials see a ready broker. Also add the grant window 15m flag to run, inject, capture, and write env invocations in TestCLIEndToEndMatrix, since the v0.1.33 hardening pass made an explicit window duration mandatory whenever any grant scope is window. [v0.1.33] Land the P0 security hardening pass: peer UID check on the daemon Unix socket, crash safe vault envelope writes, encoding aware byte range redactor, refusal of argv delivered plaintext in secret commands, write env clobber protection, scrubbing of inherited HASP env in spawned children, hardened git shell outs, per session inject directories, normalized vault unwrap errors, removal of the .test basename KDF weakening seam, and HMAC chained audit log entries under a per vault key. Migrate the vault KDF to argon2id with a backwards compatible read path, ship hasp vault rekdf to upgrade existing vaults in place, and add hasp vault forget device plus a wider hasp vault lock surface. Add operator facing CLI verbs: hasp secret show / reveal / copy, hasp secret search, hasp secret diff, hasp session list mine json, hasp audit tail [ n N] [ f], hasp completion , and inline TTY confirm for agent safe plaintext reveal/copy. Stabilize the user surface: enforce a strict json contract with structured error envelopes, introduce stable error codes and exit code buckets, standardise env NAME=@REF grammar across run / write env / app connect, replace tri state bool flags with always never ask, gate auto expose behind expose=ask always never, require explicit grant window when scope is window, accept duration shaped grant values, and deprecate hasp set / hasp capture / top level list+get shortcuts in favor of hasp secret. Polish the help and error surfaces: 'did you mean' suggestions for unknown topics and commands, distinct empty vault vs no match templates, populated Hint fields on key user facing errors, per command help bodies that list every FlagSet flag, dry run implies explain, ASCII glyph fallback under non UTF 8 locales, and an ambient json / quiet sweep across renderers. Improve daemon and broker robustness: bump daemon startup deadline to 15s, replace the os.Stat readiness check with net.Dial, memoize gitsafe.TopLevel and CanonicalProjectRoot.EvalSymlinks, surface randomHex entropy failures instead of panicking, detect pid reuse during session ResolveProcess, and parse global flags from any argv position. Continue the internal/app monolith split as foundation work: Stage 1 extracts leaf rendering primitives to internal/app/ui/, Stage 2 extracts five cycle relevant primitives to dedicated subpackages (internal/app/ttyutil/, internal/app/secrettypes/, internal/app/auditlog/, internal/app/vaultaccess/, internal/app/cmddispatch/) using a closure indirection pattern that keeps test seams in place with zero test file churn. Allocate a PTY when hasp run detects a TTY on stdout so child programs that probe for an interactive terminal keep working through the broker, and add ANSI aware streaming redaction so terminal control sequences no longer mask sensitive substrings. [v0.1.32] Close the post v0.1.31 V1 visibility remainder without widening the product: surface the stdin/shell export rescue path in hasp import help, write a paste rescue section plus V1 threat model limits and licensing and usage blocks into the packaged QUICKSTART.md, and align docs/quickstart.md with the same blocks. Reconcile the competitive baseline against shipped v0.1.31 behavior and drop outdated onboarding and generic compatible first proof notes from the public release story. Keep the Go verification bar at 100.0% statement coverage across all 13 packages. [v0.1.31] Finish V1 local first parity: complete the onboarding eval so hasp setup non interactive json bind imports reliably yields a ready brokered proof, and expose the generic compatible first proof surface through hasp agent list supported, hasp bootstrap print config, and the printed proof command. Restore 100.0% statement coverage across the Go modules and prune internal app drift, keeping the verification bar and maintenance boundaries intact as the product surface grows. [v0.1.30] Close the remaining V1 competitive gaps without widening the product: refresh the competitive baseline and matrix, restate the real V1 gaps, and add a single page visual competition matrix to the private docs. Reduce internal app drift by splitting the setup workflow into smaller maintenance boundaries. [v0.1.29] Close V1 conformance ahead of the release: finish scoped conformance work, retire completed roadmap review beads, and mark shipped versus future documentation status. Harden the agent safe broker spec after adversarial review so the brokered grant semantics stay enforced end to end under automated tests and production operator flows. [v0.1.28] Harden the agent safe path by switching generated agent configs to managed wrapper scripts, registering protected process trees with the runtime daemon, and resolving agent safe state from process ancestry before weaker env/repo fallbacks. Keep plaintext access inside agent safe sessions brokered through one time local approval grants, suppress native approval prompts under automated tests only, and preserve the production operator approval path. Raise and retain the Go verification bar at 100.0% coverage while splitting the agent setup, secret prompt/plaintext policy, and setup coverage hotspots into smaller maintenance boundaries. Fix single tarball verification for the public multi platform release manifest so operators can verify one downloaded tarball without also downloading every sibling platform archive. [v0.1.27] Stop temp home eval and release flows from leaving stray hasp daemon serve processes behind, and scope eval side CLI config writes to the test home instead of the real machine config. Harden the cleanup fallback so pidfile based teardown first verifies that the recorded PID still belongs to the expected scoped HASP daemon before it invokes daemon stop or sends kill signals. Raise the repo wide Go verification bar back to 100.0% coverage and split setup presentation helpers out of setup.go so the setup workflow and terminal rendering are no longer concentrated in one file. [v0.1.26] Harden macOS convenience unlock by targeting the explicit default keychain path for keychain set, get, and delete operations instead of relying on ambient search list behavior. Retry the setup time convenience unlock verification step before declaring it unavailable, and surface a concrete convenience unlock detail in setup output when macOS still blocks the keychain path. Keep the repo verification bar at 100.0% coverage and publish the patch through the signed release, R2 mirror, and Homebrew tap flow. [v0.1.25] Extend the launcher consent path so HASP can add its launcher directory to shell PATH, but only after the user says yes in interactive flows or passes add to path=true in scripts. Keep the new topic based help surface intact while covering the PATH edit code and rollback paths back to a deterministic 100.0% Go coverage gate. Publish the patch through the real HASP signing key, the GitHub release flow, and the configured R2 mirror. [v0.1.24] Add a real topic based CLI help surface under hasp help, hasp help ..., and command local help routes so users can learn the vault, app, agent, project, and broker concepts directly from the binary. Make launcher creation explicit in the app flow: interactive hasp app connect now asks before it writes a launcher, while scripted runs use install=true or install=false. Keep the repo coverage gate at 100.0%, keep conformance green, and publish the release with the real HASP signing key plus the configured R2 mirror path. [v0.1.23] Re cut the consumer first app and agent release with the real HASP release signing key so the published checksums, tarballs, and detached signatures no longer rely on ephemeral local signing. Keep the shipped hasp secret, hasp app, and hasp agent surfaces from v0.1.22 unchanged while publishing a clean signed patch release. [v0.1.22] Add the consumer first hasp app and hasp agent surfaces, including machine scoped app consumers, repo scoped agent connections, audited consumer profile storage, and runtime delivery for env vars, temporary files, and temporary dotenv bundles. Harden launcher ergonomics by validating app consumer names, forwarding runtime arguments through hasp app run, protecting unmanaged launcher paths from silent overwrite, and preserving rollback coverage for connect, install, and disconnect failure paths. Update the V1 and quickstart docs around the shipped consumer model while keeping the Go verification gate at 100.0% coverage and the full conformance lane green. [v0.1.21] Add the human first hasp secret CLI surface for add, update, delete, get, list, expose, and hide, plus matching MCP secret tools so coding agents can store and expose secrets without forcing the user out of chat. Tighten repo scoped secret enforcement so brokered execution no longer falls back to raw vault item names and automatic repo enablement only occurs for real git repositories. Raise the Go verification bar back to a deterministic 100.0% coverage gate, add direct branch coverage for the new secret flows, and harden local release signing scripts so ephemeral noninteractive signing works in release smoke and artifact evals. [v0.1.20] Negotiate the MCP protocol version during initialize so Claude accepts hasp mcp instead of rejecting the hard coded 2026 04 13 handshake. Keep compatibility with stricter clients by preferring the stable 2025 06 18 MCP protocol while still tolerating clients that explicitly request the newer version. [v0.1.19] Keep hasp setup responsive after password entry by time bounding the optional macOS convenience unlock enable and verification path instead of waiting on slow keychain failures. Skip macOS convenience unlock setup entirely when no usable default keychain exists, so setup falls back cleanly instead of surfacing the Keychain Not Found system dialog. [v0.1.18] Stop hasp mcp from replying to JSON RPC notifications, so Codex no longer fails MCP startup with Transport closed during the notifications/initialized handshake. Add regression coverage for the initialize plus notification handshake so future releases keep the MCP stream valid for stricter clients. [v0.1.17] Rework the interactive hasp setup confirmation and completion screens into grouped, aligned blocks so machine defaults, agent targets, statuses, and next steps are easier to scan at a glance. Add stronger TTY only color hierarchy for stage bullets, config paths, summary labels, statuses, and numbered next steps while keeping non TTY output clean and the 100.0% coverage gate intact. [v0.1.15] Support noninteractive GPG signing for public release packaging with HASP RELEASE GPG PASSPHRASE or HASP RELEASE GPG PASSPHRASE FILE, so passphrase protected release keys work in CI and scripted maintainer flows. Extend the release smoke lane to cover passphrase protected signing for both packaged release sidecars and assembled public release metadata, while keeping the public export verification lane green. [v0.1.14] Tighten the interactive hasp setup presentation so stage guidance uses cleaner bullets, TTY color accents, and a standalone success lead instead of the old indented summary line. Lock the setup output polish down with exact output regressions while keeping the absolute MCP command path fix and the 100.0% coverage gate intact. [v0.1.13] Write absolute hasp command paths into generated Codex and JSON MCP client configs so launcher environments do not depend on ambient PATH resolution. Keep the setup retry fix, convenience unlock compatibility fix, truthful version reporting, and 100.0% coverage gate intact. [v0.1.12] Store convenience unlock key material in a keychain compatible encoded form and decode it on readback, so macOS convenience unlock works reliably on real installed binaries. Keep the existing vault setup retry fix, truthful embedded version reporting, and 100.0% coverage gate intact. [v0.1.11] Embed the build version into HASP binaries so hasp version reports the binary’s own release identity instead of reading a nearby repo VERSION file from the current working directory. Keep the existing vault setup retry fix and 100.0% coverage gate intact while making stale installed binaries easier to detect. [v0.1.10] Re cut the setup retry fix release from a real PTY validated HEAD so the published version is unambiguous. Preserve the existing vault password retry behavior, convenience unlock verification, and the integration regressions added for both paths. [v0.1.9] Keep interactive hasp setup on the existing vault password prompt after a wrong password instead of aborting the whole flow. Add integration coverage for the exact retry path so future releases catch this regression automatically. [v0.1.8] Verify convenience unlock during hasp setup by reopening the vault through the keychain path before reporting success. Return a clearer CLI error when neither HASP MASTER PASSWORD nor convenience unlock is available for a vault opening command. Add integration coverage for the exact setup/status regression so future releases catch this mismatch automatically. [v0.1.7] Add hasp project adopt under [ preview] so operators can scan and enroll multiple local git repos using machine defaults without background crawling. Extend the CLI integration coverage and edge case tests for bulk adoption and password iteration selection, bringing the repo Go coverage gate back to 100.0%. Keep the curated public export boundary valid while landing the new V1 adoption path. [v0.1.6] Shift hasp setup to a machine wide onboarding model with defaults for automatic project adoption on first use. Auto create local project bindings from machine defaults when HASP is first used in a project, instead of requiring manual per repo setup. Keep repo scoped enforcement under the hood while removing the repo by repo onboarding tax. Maintain the corrected repo coverage gate at 100.0%. [v0.1.5] When interactive hasp setup master password confirmation does not match, setup now retries the password step in place instead of aborting the whole flow. Keep the retry path fully covered while preserving the corrected 100.0% repo coverage gate. [v0.1.4] Ignore saved setup defaults that point into ephemeral temp directories, so stale test or temp paths no longer show up as the default local HASP data directory. Tighten the hasp setup terminal layout with clearer visual stage separators and more compact guidance lines. Keep the redesigned setup flow fully covered and the corrected repo coverage gate at 100.0%. [v0.1.3] Replace the freeform interactive agent prompt in hasp setup with a numbered agent selection menu. Add a final review and confirm screen before hasp setup writes local vault, repo, or agent config changes. Keep interactive setup human readable while preserving json and non interactive automation paths. Maintain a stable default go test ./... path and a corrected 100.0% coverage gate after the setup redesign. [v0.1.2] Redesign hasp setup into a more contextual staged onboarding flow with clearer machine, repo, and agent guidance. Stop stale saved setup paths from surfacing dead temp directories as the default local HASP data path. Keep interactive setup human readable while preserving json and non interactive machine output for automation. Stabilize the default parallel Go test path while keeping the corrected coverage gate at 100.0%. [v0.1.1] Add the new hasp setup flow for first run machine, repo, and agent MCP configuration. Expand bootstrap, doctor, and operator guidance so local install and setup are easier to verify end to end. Harden the packaged release lifecycle with verify, install, upgrade, uninstall, hosted artifact publication, and Homebrew tap updates. Improve test and coverage rigor, including deterministic 100.0% coverage and a stable default go test ./... path in test binaries. [v0.1.0] Initial public export and release publication lane setup. Public release workflow for GitHub Releases, Cloudflare R2 mirroring, and Homebrew tap publication. Signed packaged releases with verification material and artifact pinned formula generation. ================================================================================ Release / Release distribution URL: https://gethasp.com/docs/v0.1.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 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 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. 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/v0.1.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 install path: The planned public tap is gethasp/homebrew tap. 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/ /. 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/v0.1.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 advisory repo metadata, not authorization. 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/v0.1.36/cli-reference/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md -------------------------------------------------------------------------------- HASP CLI reference Build: 0.1.36 (unknown) 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 vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes ================================================================================ Reference / Errors URL: https://gethasp.com/docs/v0.1.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 . 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/v0.1.35/overview/ Source: https://github.com/gethasp/hasp/blob/main/public/README.md -------------------------------------------------------------------------------- HASP HASP is a local first broker for managed secrets in agent workflows. It is built for people using coding agents on normal developer machines who need the agent to do useful work without turning .env files, copied tokens, and repo local credentials into the default operating model. What this public repo contains This repo contains the public code and release surface for: the Go broker and CLI under apps/server/ the public docs needed to build, test, verify, and install shipped releases This public repo is limited to the server/CLI release surface. Closed source apps, hosted services, marketing assets, and private planning docs stay outside this export. What HASP does stores managed secrets in a local encrypted vault brokers secret access to commands and agent tooling supports safe brokered execution through run, inject, and MCP flows provides audited convenience materialization when an operator explicitly asks for it installs repo guardrails so managed secrets do not get committed or deployed by accident The core rule is simple: In broker managed agent safe flows, managed secret values must not enter agent context. Start locally Source build: Packaged release: If you want the short path first, start with QUICKSTART.md. If you already installed HASP with Homebrew and want the step by step setup, start with docs/after homebrew.md. Release model tagged releases publish signed release artifacts release assets can be mirrored to Cloudflare R2 behind a stable download host Homebrew support is artifact based, not source build based For the maintainer flow, see RELEASING.md. Public repo rule This repo is a curated public export of the canonical source tree. If maintainers accept a public PR, they replay the change through the canonical source tree and sync the public export back here before merging or tagging the release. Where to go next QUICKSTART.md docs/README.md SUPPORT.md SECURITY.md CONTRIBUTING.md ================================================================================ Start / Quickstart URL: https://gethasp.com/docs/v0.1.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 with Homebrew and want the full beginner flow, read docs/after homebrew.md. 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/v0.1.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, build.config, 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. 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 / After Homebrew URL: https://gethasp.com/docs/v0.1.35/after-homebrew/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/after-homebrew.md -------------------------------------------------------------------------------- I installed HASP with Homebrew. Now what? This guide is for the most common starting point: you already ran brew tap gethasp/homebrew tap you already ran brew install 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 Homebrew. It can: 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 is the manual flow and troubleshooting fallback. The normal path is guided The Homebrew 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 common day to day surface should look like: hasp secret add hasp app connect hasp agent connect not repeated command wrapping or repeated repo/bootstrap thinking. Use the manual sections below only when you want to inspect one layer, automate a specific step, or recover from a failed setup. 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 Homebrew'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 actually 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 Generic compatible profiles are also available when they match your agent, but they are not first class support claims yet: 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=secret 01 Put the secret bound to secret 01 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 actually do day to day You usually need only three commands. A. Run a command with a secret Use this whenever you can. B. Materialize a file only when you really need to Use this only when a tool absolutely requires a real file. This is convenience mode, not the safest path. C. Check what HASP has been doing Use that if you want to review imports, approvals, backup/restore events, and similar actions. 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 you write a real file, that file is truly real: 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 If you want the absolute minimum happy path, this is it: If those commands work, you are ready to connect your coding agent. ================================================================================ Start / Install URL: https://gethasp.com/docs/v0.1.35/install/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/install.md -------------------------------------------------------------------------------- Install HASP Source build Packaged release Default install prefix: Installed binary: Upgrade Uninstall The default uninstall path removes the installed release tree only. ================================================================================ Operate / Command guide URL: https://gethasp.com/docs/v0.1.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 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 or Secrets.example.xcconfig. 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 such as a macOS xcconfig file, 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. 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. 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/v0.1.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 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. 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/v0.1.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. 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, build.config, 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. ================================================================================ Agents / Agent Profiles URL: https://gethasp.com/docs/v0.1.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. 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 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. OpenClaw Hermes 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/v0.1.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 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 plus the same canonical secret set, not just alias names. 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/v0.1.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 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/v0.1.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/v0.1.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/v0.1.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 / OpenClaw URL: https://gethasp.com/docs/v0.1.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/v0.1.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 repo 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 with the alias or named reference printed by setup (e.g. secret 01 or @OPENAI API KEY). 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 clearly 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/v0.1.35/changelog/ Source: https://github.com/gethasp/hasp/blob/main/public/CHANGELOG.md -------------------------------------------------------------------------------- Changelog All notable public releases should be summarized here. Unreleased [v0.1.35] Ship value free repo requirements and target scoped delivery in .hasp.manifest.json: strict schema validation, safe project inspection, placeholder example generation, and project doctor diagnostics for stale examples, unavailable commands, unignored generated outputs, workspace visible secret delivery, kind mismatches, and manifest drift without exposing values or repo controlled command output. Add target expansion to hasp run, hasp inject, and hasp write env while preserving normal binding, grant, redaction, audit, and convenience materialization rules. Target expansion now records local review state and warns when command argv, refs, delivery sets, or output paths drift after review. Add target aware app and MCP surfaces: hasp app connect target, hasp targets, hasp target explain, and target aware MCP run/inject. Agent target listing and explain omit command argv and raw values. Update public docs and the docs site with repo target guidance, a regenerated CLI reference, and status/conformance entries for the shipped target manifest contract. [v0.1.34] Close the staff review hardening backlog before publication: strict doctor JSON allowlist enforcement, documented E error classification for plain CLI failures, read only doctor diagnostics by default, symlink safe write env, inherited backup passphrase stripping for brokered children, shared CLI/MCP repository scanning, capped MCP tool output, and narrower first screen CLI help. Downgrade release trust claims to match the real packaged artifacts: signatures still verify, while SBOM, provenance, code signing status, and reproducible build status are documented as local metadata sidecars rather than remote attestation. Add large vault, large output, MCP, and repo scan benchmark smoke coverage so future hardening work has performance evidence instead of relying on small fixtures. Fix the public release CI lane: add TestMain HASP HOME defaults to apps/server/cmd/hasp and apps/server/internal/runner so the paths.Resolve test isolation guard does not fire on packages that previously relied on a real /.hasp fallback. Make the canonical root cache invalidation test deterministic on Linux tmpfs by replacing RemoveAll+Mkdir (which can reuse the same inode immediately) with a sibling create plus rename, guaranteeing a distinct inode for os.SameFile. Stabilize two CI only flakes: poll for the daemon pid file (not just the socket) before StopDaemon in TestDaemonCommandStartBranch, and widen the GrantOnce TTL in TestEnforceSecretPlaintextPolicyConsumeFailure so the assertion remains focused on the persist failure path under heavy CI load. Fix a Linux only PTY drain race in executePTY where fast exit children like printf hello pty could lose their final bytes: wait for the master→stdout io.Copy goroutine to finish (slave close naturally surfaces buffered data plus EIO on the master) before force closing ptmx, with a 100ms timeout fallback so detached grandchildren that kept the slave fd open cannot stall the runner. Widen the four remaining 2 second daemon shutdown safety caps in test helpers (internal/mcp, internal/brokerops, internal/runtime, plus the second internal/app helper) to 10 seconds so a slow scheduler tick during the public release coverage lane no longer fails an otherwise clean test cleanup. Fix a daemon readiness race in the internal/evals integration helpers: after the v0.1.33 change that made hasp status connect only, the helpers were switched to hasp daemon start, but StartDaemon returns as soon as the broker is spawned (before the Unix socket is bound), so TestCLISessionLifecycleEval and TestStopEvalDaemonStopsDetachedDaemon could race the dial. Add a waitForEvalSocket poll (15s deadline, 25ms tick) immediately after each daemon start so dependent dials see a ready broker. Also add the grant window 15m flag to run, inject, capture, and write env invocations in TestCLIEndToEndMatrix, since the v0.1.33 hardening pass made an explicit window duration mandatory whenever any grant scope is window. [v0.1.33] Land the P0 security hardening pass: peer UID check on the daemon Unix socket, crash safe vault envelope writes, encoding aware byte range redactor, refusal of argv delivered plaintext in secret commands, write env clobber protection, scrubbing of inherited HASP env in spawned children, hardened git shell outs, per session inject directories, normalized vault unwrap errors, removal of the .test basename KDF weakening seam, and HMAC chained audit log entries under a per vault key. Migrate the vault KDF to argon2id with a backwards compatible read path, ship hasp vault rekdf to upgrade existing vaults in place, and add hasp vault forget device plus a wider hasp vault lock surface. Add operator facing CLI verbs: hasp secret show / reveal / copy, hasp secret search, hasp secret diff, hasp session list mine json, hasp audit tail [ n N] [ f], hasp completion , and inline TTY confirm for agent safe plaintext reveal/copy. Stabilize the user surface: enforce a strict json contract with structured error envelopes, introduce stable error codes and exit code buckets, standardise env NAME=@REF grammar across run / write env / app connect, replace tri state bool flags with always never ask, gate auto expose behind expose=ask always never, require explicit grant window when scope is window, accept duration shaped grant values, and deprecate hasp set / hasp capture / top level list+get shortcuts in favor of hasp secret. Polish the help and error surfaces: 'did you mean' suggestions for unknown topics and commands, distinct empty vault vs no match templates, populated Hint fields on key user facing errors, per command help bodies that list every FlagSet flag, dry run implies explain, ASCII glyph fallback under non UTF 8 locales, and an ambient json / quiet sweep across renderers. Improve daemon and broker robustness: bump daemon startup deadline to 15s, replace the os.Stat readiness check with net.Dial, memoize gitsafe.TopLevel and CanonicalProjectRoot.EvalSymlinks, surface randomHex entropy failures instead of panicking, detect pid reuse during session ResolveProcess, and parse global flags from any argv position. Continue the internal/app monolith split as foundation work: Stage 1 extracts leaf rendering primitives to internal/app/ui/, Stage 2 extracts five cycle relevant primitives to dedicated subpackages (internal/app/ttyutil/, internal/app/secrettypes/, internal/app/auditlog/, internal/app/vaultaccess/, internal/app/cmddispatch/) using a closure indirection pattern that keeps test seams in place with zero test file churn. Allocate a PTY when hasp run detects a TTY on stdout so child programs that probe for an interactive terminal keep working through the broker, and add ANSI aware streaming redaction so terminal control sequences no longer mask sensitive substrings. [v0.1.32] Close the post v0.1.31 V1 visibility remainder without widening the product: surface the stdin/shell export rescue path in hasp import help, write a paste rescue section plus V1 threat model limits and licensing and usage blocks into the packaged QUICKSTART.md, and align docs/quickstart.md with the same blocks. Reconcile the competitive baseline against shipped v0.1.31 behavior and drop outdated onboarding and generic compatible first proof notes from the public release story. Keep the Go verification bar at 100.0% statement coverage across all 13 packages. [v0.1.31] Finish V1 local first parity: complete the onboarding eval so hasp setup non interactive json bind imports reliably yields a ready brokered proof, and expose the generic compatible first proof surface through hasp agent list supported, hasp bootstrap print config, and the printed proof command. Restore 100.0% statement coverage across the Go modules and prune internal app drift, keeping the verification bar and maintenance boundaries intact as the product surface grows. [v0.1.30] Close the remaining V1 competitive gaps without widening the product: refresh the competitive baseline and matrix, restate the real V1 gaps, and add a single page visual competition matrix to the private docs. Reduce internal app drift by splitting the setup workflow into smaller maintenance boundaries. [v0.1.29] Close V1 conformance ahead of the release: finish scoped conformance work, retire completed roadmap review beads, and mark shipped versus future documentation status. Harden the agent safe broker spec after adversarial review so the brokered grant semantics stay enforced end to end under automated tests and production operator flows. [v0.1.28] Harden the agent safe path by switching generated agent configs to managed wrapper scripts, registering protected process trees with the runtime daemon, and resolving agent safe state from process ancestry before weaker env/repo fallbacks. Keep plaintext access inside agent safe sessions brokered through one time local approval grants, suppress native approval prompts under automated tests only, and preserve the production operator approval path. Raise and retain the Go verification bar at 100.0% coverage while splitting the agent setup, secret prompt/plaintext policy, and setup coverage hotspots into smaller maintenance boundaries. Fix single tarball verification for the public multi platform release manifest so operators can verify one downloaded tarball without also downloading every sibling platform archive. [v0.1.27] Stop temp home eval and release flows from leaving stray hasp daemon serve processes behind, and scope eval side CLI config writes to the test home instead of the real machine config. Harden the cleanup fallback so pidfile based teardown first verifies that the recorded PID still belongs to the expected scoped HASP daemon before it invokes daemon stop or sends kill signals. Raise the repo wide Go verification bar back to 100.0% coverage and split setup presentation helpers out of setup.go so the setup workflow and terminal rendering are no longer concentrated in one file. [v0.1.26] Harden macOS convenience unlock by targeting the explicit default keychain path for keychain set, get, and delete operations instead of relying on ambient search list behavior. Retry the setup time convenience unlock verification step before declaring it unavailable, and surface a concrete convenience unlock detail in setup output when macOS still blocks the keychain path. Keep the repo verification bar at 100.0% coverage and publish the patch through the signed release, R2 mirror, and Homebrew tap flow. [v0.1.25] Extend the launcher consent path so HASP can add its launcher directory to shell PATH, but only after the user says yes in interactive flows or passes add to path=true in scripts. Keep the new topic based help surface intact while covering the PATH edit code and rollback paths back to a deterministic 100.0% Go coverage gate. Publish the patch through the real HASP signing key, the GitHub release flow, and the configured R2 mirror. [v0.1.24] Add a real topic based CLI help surface under hasp help, hasp help ..., and command local help routes so users can learn the vault, app, agent, project, and broker concepts directly from the binary. Make launcher creation explicit in the app flow: interactive hasp app connect now asks before it writes a launcher, while scripted runs use install=true or install=false. Keep the repo coverage gate at 100.0%, keep conformance green, and publish the release with the real HASP signing key plus the configured R2 mirror path. [v0.1.23] Re cut the consumer first app and agent release with the real HASP release signing key so the published checksums, tarballs, and detached signatures no longer rely on ephemeral local signing. Keep the shipped hasp secret, hasp app, and hasp agent surfaces from v0.1.22 unchanged while publishing a clean signed patch release. [v0.1.22] Add the consumer first hasp app and hasp agent surfaces, including machine scoped app consumers, repo scoped agent connections, audited consumer profile storage, and runtime delivery for env vars, temporary files, and temporary dotenv bundles. Harden launcher ergonomics by validating app consumer names, forwarding runtime arguments through hasp app run, protecting unmanaged launcher paths from silent overwrite, and preserving rollback coverage for connect, install, and disconnect failure paths. Update the V1 and quickstart docs around the shipped consumer model while keeping the Go verification gate at 100.0% coverage and the full conformance lane green. [v0.1.21] Add the human first hasp secret CLI surface for add, update, delete, get, list, expose, and hide, plus matching MCP secret tools so coding agents can store and expose secrets without forcing the user out of chat. Tighten repo scoped secret enforcement so brokered execution no longer falls back to raw vault item names and automatic repo enablement only occurs for real git repositories. Raise the Go verification bar back to a deterministic 100.0% coverage gate, add direct branch coverage for the new secret flows, and harden local release signing scripts so ephemeral noninteractive signing works in release smoke and artifact evals. [v0.1.20] Negotiate the MCP protocol version during initialize so Claude accepts hasp mcp instead of rejecting the hard coded 2026 04 13 handshake. Keep compatibility with stricter clients by preferring the stable 2025 06 18 MCP protocol while still tolerating clients that explicitly request the newer version. [v0.1.19] Keep hasp setup responsive after password entry by time bounding the optional macOS convenience unlock enable and verification path instead of waiting on slow keychain failures. Skip macOS convenience unlock setup entirely when no usable default keychain exists, so setup falls back cleanly instead of surfacing the Keychain Not Found system dialog. [v0.1.18] Stop hasp mcp from replying to JSON RPC notifications, so Codex no longer fails MCP startup with Transport closed during the notifications/initialized handshake. Add regression coverage for the initialize plus notification handshake so future releases keep the MCP stream valid for stricter clients. [v0.1.17] Rework the interactive hasp setup confirmation and completion screens into grouped, aligned blocks so machine defaults, agent targets, statuses, and next steps are easier to scan at a glance. Add stronger TTY only color hierarchy for stage bullets, config paths, summary labels, statuses, and numbered next steps while keeping non TTY output clean and the 100.0% coverage gate intact. [v0.1.15] Support noninteractive GPG signing for public release packaging with HASP RELEASE GPG PASSPHRASE or HASP RELEASE GPG PASSPHRASE FILE, so passphrase protected release keys work in CI and scripted maintainer flows. Extend the release smoke lane to cover passphrase protected signing for both packaged release sidecars and assembled public release metadata, while keeping the public export verification lane green. [v0.1.14] Tighten the interactive hasp setup presentation so stage guidance uses cleaner bullets, TTY color accents, and a standalone success lead instead of the old indented summary line. Lock the setup output polish down with exact output regressions while keeping the absolute MCP command path fix and the 100.0% coverage gate intact. [v0.1.13] Write absolute hasp command paths into generated Codex and JSON MCP client configs so launcher environments do not depend on ambient PATH resolution. Keep the setup retry fix, convenience unlock compatibility fix, truthful version reporting, and 100.0% coverage gate intact. [v0.1.12] Store convenience unlock key material in a keychain compatible encoded form and decode it on readback, so macOS convenience unlock works reliably on real installed binaries. Keep the existing vault setup retry fix, truthful embedded version reporting, and 100.0% coverage gate intact. [v0.1.11] Embed the build version into HASP binaries so hasp version reports the binary’s own release identity instead of reading a nearby repo VERSION file from the current working directory. Keep the existing vault setup retry fix and 100.0% coverage gate intact while making stale installed binaries easier to detect. [v0.1.10] Re cut the setup retry fix release from a real PTY validated HEAD so the published version is unambiguous. Preserve the existing vault password retry behavior, convenience unlock verification, and the integration regressions added for both paths. [v0.1.9] Keep interactive hasp setup on the existing vault password prompt after a wrong password instead of aborting the whole flow. Add integration coverage for the exact retry path so future releases catch this regression automatically. [v0.1.8] Verify convenience unlock during hasp setup by reopening the vault through the keychain path before reporting success. Return a clearer CLI error when neither HASP MASTER PASSWORD nor convenience unlock is available for a vault opening command. Add integration coverage for the exact setup/status regression so future releases catch this mismatch automatically. [v0.1.7] Add hasp project adopt under [ preview] so operators can scan and enroll multiple local git repos using machine defaults without background crawling. Extend the CLI integration coverage and edge case tests for bulk adoption and password iteration selection, bringing the repo Go coverage gate back to 100.0%. Keep the curated public export boundary valid while landing the new V1 adoption path. [v0.1.6] Shift hasp setup to a machine wide onboarding model with defaults for automatic project adoption on first use. Auto create local project bindings from machine defaults when HASP is first used in a project, instead of requiring manual per repo setup. Keep repo scoped enforcement under the hood while removing the repo by repo onboarding tax. Maintain the corrected repo coverage gate at 100.0%. [v0.1.5] When interactive hasp setup master password confirmation does not match, setup now retries the password step in place instead of aborting the whole flow. Keep the retry path fully covered while preserving the corrected 100.0% repo coverage gate. [v0.1.4] Ignore saved setup defaults that point into ephemeral temp directories, so stale test or temp paths no longer show up as the default local HASP data directory. Tighten the hasp setup terminal layout with clearer visual stage separators and more compact guidance lines. Keep the redesigned setup flow fully covered and the corrected repo coverage gate at 100.0%. [v0.1.3] Replace the freeform interactive agent prompt in hasp setup with a numbered agent selection menu. Add a final review and confirm screen before hasp setup writes local vault, repo, or agent config changes. Keep interactive setup human readable while preserving json and non interactive automation paths. Maintain a stable default go test ./... path and a corrected 100.0% coverage gate after the setup redesign. [v0.1.2] Redesign hasp setup into a more contextual staged onboarding flow with clearer machine, repo, and agent guidance. Stop stale saved setup paths from surfacing dead temp directories as the default local HASP data path. Keep interactive setup human readable while preserving json and non interactive machine output for automation. Stabilize the default parallel Go test path while keeping the corrected coverage gate at 100.0%. [v0.1.1] Add the new hasp setup flow for first run machine, repo, and agent MCP configuration. Expand bootstrap, doctor, and operator guidance so local install and setup are easier to verify end to end. Harden the packaged release lifecycle with verify, install, upgrade, uninstall, hosted artifact publication, and Homebrew tap updates. Improve test and coverage rigor, including deterministic 100.0% coverage and a stable default go test ./... path in test binaries. [v0.1.0] Initial public export and release publication lane setup. Public release workflow for GitHub Releases, Cloudflare R2 mirroring, and Homebrew tap publication. Signed packaged releases with verification material and artifact pinned formula generation. ================================================================================ Release / Release distribution URL: https://gethasp.com/docs/v0.1.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 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 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. 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/v0.1.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 install path: The planned public tap is gethasp/homebrew tap. 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/ /. 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/v0.1.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 advisory repo metadata, not authorization. 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/v0.1.35/cli-reference/ Source: https://github.com/gethasp/hasp/blob/main/public/docs/cli-reference.md -------------------------------------------------------------------------------- HASP CLI reference Build: 0.1.35 (unknown) 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 vault hasp vault lock hasp vault forget device hasp vault rekey hasp status hasp ping hasp audit hasp audit tail hasp export backup hasp upgrade hasp docs hasp internals hasp exit codes ================================================================================ Reference / Errors URL: https://gethasp.com/docs/v0.1.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 . 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: