Agent quickstart

This page is written for you, the agent. It tells you how to use development secrets without reading them during the normal workflow. Runtime injection does not enforce unreadability: if you control the child process, you can inspect its environment. If you are a human wiring up an agent, copy the AGENTS.md snippet at the bottom into your repo and your agent will find its way here.

The rules

1. Never display, inspect, log, or ask the user to paste a secret value into the conversation. Let insecur import read an explicitly identified project dotenv file directly.
2. Use --json for product commands. Output is metadata only, by contract. insecur guide is the exception: it intentionally emits offline Markdown playbooks.
3. Secrets reach code through insecur run, which injects them into one child process. That is the only delivery path you need.
4. Branch on exit codes, not on message text. Messages change; codes and remediation commands do not.
5. If the intended credential is missing or rejected, stop. Do not search other projects, home-directory credentials, agent settings, history, or transcripts for a substitute. A matching variable name or token format does not establish the right account or permissions.
6. Never generate a replacement for a third-party API key. Random generation is only for application-owned secrets such as signing keys, when their creation or replacement is authorized.

Implement in an existing project

Follow this procedure when the user hands you this page to adopt insecur. Local Mode needs no account or hosted login. It stores encrypted values on this machine and supports one injected variable per run. Use macOS or Linux: Windows runtime injection currently fails closed because descendant-process containment is not implemented.

Install and select the project

Install the GitHub CLI with gh attestation support first. The insecur installer verifies the binary checksum and GitHub build attestation. See Installation for platform details and installer trust requirements.

curl -fsSL https://insecur.cloud/install.sh | sh
insecur --version

Start at the intended checkout's root. Inspect existing non-secret .insecur.json and application configuration code, without reading dotenv contents. Check the resolved configuration:

insecur config show --json

Preserve an existing binding. Check projectConfigPath, project, and environment against this checkout's config. Explicit flags and INSECUR_* scope variables can override project defaults; stop on an unexpected selection instead of silently repointing the project.

If the project has no config, initialize Local Mode explicitly from its root:

insecur init --host local --json

Do not replace an existing hosted config with a local one. Follow the established authentication and policy setup for a hosted project.

Import the intended credential

The examples use OPENROUTER_API_KEY; substitute the exact variable your application uses. Confirm the provider account, credential purpose, and source file with the user if unknown. For a dotenv file the user has identified as belonging to this project:

insecur import .env --dry-run --json
insecur import .env --json
insecur secrets list --json

Review the metadata-only dry-run plan before importing. File arguments are relative to the invocation directory. An approved source in the primary checkout can be passed by its exact path while retaining this project's target config. Do not search for it, parse it with a shell pipeline, or execute it with source.

Import is create-only. Preflight rejects conflicts before writes start; a later write failure can leave partial progress, reported in the error. Reconcile that progress before retrying. The source file is preserved.

Without an approved source file, ask the human to supply the intended credential in their own terminal with insecur secrets set OPENROUTER_API_KEY --value-stdin. Do not receive the value. A listed key without a current version still needs a value on this machine.

Wrap the normal command

Prefix the project's existing application or evaluation command with insecur run. For example, if its eval script currently runs node scripts/evaluate.mjs, update that same script:

{
  "scripts": {
    "eval": "insecur run --variable-key OPENROUTER_API_KEY -- node scripts/evaluate.mjs"
  }
}

Keep the project's real executable and arguments. Do not recursively invoke the wrapped script or give the provider key to the whole agent session. The application must require its selected environment variable. Remove any application fallback that overrides it from another credential file.

Local Mode supports one variable per run. Multi-secret policy runs require hosted mode; nesting insecur run does not combine keys. Each child gets a small OS environment baseline, including PATH and HOME, plus the selected value. Other ambient variables, including non-secret settings, are excluded. Supply necessary non-secret settings through normal application arguments or config. The child retains filesystem access, so libraries that search HOME for credentials need explicit configuration too.

Verify the application and a fresh worktree

Plan the actual command first:

insecur run --variable-key OPENROUTER_API_KEY --plan --json -- node scripts/evaluate.mjs

Inspect data.plan.ready, variableKeys, projectId, and environmentId. A plan returns exit 0 even when ready is false and issues no grant. Check projectConfigPath when provided; insecur config show --json also reports the selected path. Respect each next action's actor: human means hand off, not permission to obtain the value yourself.

Run the normal project command and its smallest meaningful provider-backed check:

npm run eval

Use the project's actual package manager and command. A ready plan proves a stored value exists, not that the provider accepts its account, permissions, model access, or credit balance. If the provider rejects it, ask the owner to correct this binding rather than trying another key.

Commit .insecur.json, the command change, and the agent instructions below. The config contains references and secret names, not values. Never commit local stores, machine keys, or plaintext credential files. Create a fresh worktree from a branch containing that commit, then repeat config show, secrets list, the plan, and the real application check from its root.

On the same machine and OS user, the committed config selects the same encrypted local value. Do not copy .env into the worktree or initialize a replacement project there. On another machine, insecur init --host local --json adopts committed metadata; the owner must supply the intended values on that machine.

Current source builds discover config from subdirectories within the current Git checkout. For released CLIs without that behavior, run from the checkout root or pass --config-dir with its exact config directory. See Local Mode for discovery boundaries.

Verify failure and finish cleanup

Choose a variable that secrets list confirms is absent. If INSECUR_MISSING_PROOF is absent:

insecur run --variable-key INSECUR_MISSING_PROOF --json -- node -e "console.error('CHILD_STARTED'); process.exit(99)"

Expect a nonzero missing-secret error and no CHILD_STARTED output. Ambient credentials and same-named secrets in other projects must not satisfy this request. Do not delete a real value to test failure.

After the real application check passes, follow dotenv migration to remove only the approved plaintext source. Preserve needed non-secret settings, obtain authorization before deleting files, and do not create extra plaintext backups. Run insecur scan --strict --json after cleanup; a clean scan covers its configured paths and detectors, not every copy on the machine.

Done

Report the normal command, selected config path, successful application check from the fresh worktree, missing-key failure without child execution, and cleanup result. Identify any remaining human handoff. Never include values. A configuration-only check is not end-to-end verification.

Orient yourself

Check whether a session exists and what scope is resolved:

insecur whoami --json

Exit 0 means the command resolved the context it could. In hosted mode, inspect the returned session and scope fields instead of assuming organization, project, and environment are all present. Local Mode has no hosted session and can also return 0. Exit 3 in hosted mode means no session: stop and ask the human to run insecur login, or run insecur login --device in a headless environment where the human can approve the device code.

See what secrets the environment expects:

insecur secrets list --json

Use a secret

Run any command with a secret injected into its environment:

insecur run --variable-key DATABASE_URL -- pnpm dev

The -- separator is required. The CLI does not print the value or include it in the audit log. The child process receives it, so do not inspect, print, or log that process's environment. Each run consumes a fresh one-use grant and writes an audit event attributing it to you.

Create a secret

For a new application-owned signing secret, generation avoids copying the value:

insecur secrets set WEBHOOK_SIGNING_SECRET --generate random --length 32 --json

If the value must come from a human (a third-party API key), ask the human to run the write themselves with --value-stdin. Do not accept the value into your own context.

Handle failures

Every failure returns a stable error code, an RFC 9457 type URI you can fetch for details, and, when one exists, copy-pasteable remediation commands in the --json envelope. The short version:

Exit	Meaning	What you should do
3	Auth required	Ask the human to log in, or use insecur login --device
4	Forbidden	Stop; the session lacks scope. Report it, do not retry
7	Action required	Read the error; something external needs fixing first
8	Retryable	Back off and retry
10	Human step-up required	Take the operationId from the error and poll: insecur operations wait <operation-id> --json. A human clears it in the web console. Do not try to work around the gate

The full tables are exit codes and error codes.

Keep the project clean

Before and after you touch a project, you can check for plaintext secret exposure without an account:

insecur scan --json

insecur scan --strict exits 7 when it finds likely secrets, which makes it a usable gate in hooks and CI. insecur guide hooks prints ready-made hook recipes for Claude Code and Codex.

Read the rest of these docs

Every page here is available as raw markdown: append .md to any docs URL, or start from llms.txt for the index and llms-full.txt for the entire documentation in one file.

Tell your agents about insecur (AGENTS.md)

Humans: paste this into your repo's AGENTS.md (or CLAUDE.md), adjusted to taste.

## Secrets

This project uses insecur for secrets. There are no readable secret values in
this repo and there should never be. A process launched with `insecur run` does
receive the selected values, so do not inspect, print, or log its environment.

- Never display `.env` contents or ask me to paste a secret value. Import only an
  explicitly identified project file with `insecur import`.
- Use this checkout's committed `.insecur.json`. Inspect selection with
  `insecur config show --json`; do not repoint it to fix a missing key.
- Never search other projects, home-directory credentials, agent settings,
  history, or transcripts for a substitute credential.
- Run anything that needs secrets through `insecur run --variable-key <KEY> -- <command>`.
- List available keys with `insecur secrets list --json`.
- If an API key is missing or rejected, stop and ask its owner to supply or correct
  it using `insecur secrets set <KEY> --value-stdin`. Never generate a substitute.
- Local Mode needs no login and injects one selected variable per run.
- On exit code 3, tell me to run `insecur login`. On exit code 10, poll
  `insecur operations wait <operation-id> --json` while I approve in the web console.
- Full agent instructions: https://insecur.cloud/docs/agent-quickstart.md

Related

• Using insecur with coding agents: the human-facing view, attribution tiers, agent shell
• Quickstart: the human first-run loop
• CLI reference: every command and flag