Getting started

Ingrain Security runs inside your coding agent and threat-models an implementation plan as part of planning. The Ingrain CLI gives it your organization’s security rules, so its mitigations follow established practice.

Setting both up takes four steps.

1. Install the plugin

The ingrain-security plugin lives at github.com/ingrainlabs/ingrain-security. Add the marketplace to your coding agent, then install the plugin.

In Claude Code:

/plugin marketplace add ingrainlabs/ingrain-security

In Codex:

codex plugin marketplace add ingrainlabs/ingrain-security

Installs are pinned to the v<version> git tag, so you only ever receive tagged releases.

Windows requires Git for Windows

The plugin’s hooks run through a cmd/bash polyglot wrapper, which needs a bash on your PATH. Git for Windows provides one — install it before the plugin.

The plugin works standalone

Step 1 is enough to start threat-modeling plans — the plugin runs on its own, without the Ingrain CLI.

The Ingrain CLI is what connects it to the Ingrain Context Platform, so its mitigations follow your organization’s own security rules.

2. Install the Ingrain CLI

The Ingrain CLI ships as a single self-contained binary and runs on macOS, Linux, and Windows (x86_64 or arm64; Windows is x86_64 only). Prebuilt binaries are distributed through the public proxy at cli.ingrainlabs.dev.

Run the one-liner for your platform.

On macOS and Linux:

curl -fsSL https://cli.ingrainlabs.dev/install.sh | sh

On Windows (PowerShell):

irm https://cli.ingrainlabs.dev/install.ps1 | iex

The installer downloads the latest release binary, verifies its SHA-256 sum against the release manifest, and places ingrain on your PATH. Confirm it is there:

ingrain --help

This prints Usage: ingrain ... and the available subcommands. If it errors instead, see Troubleshooting below.

3. Create an API token

Open the Ingrain Context Platform and select Ingrain CLI configuration in the sidebar. On the Ingrain API Token page, optionally give the token a label, then generate it.

The token is scoped to your organization, begins with ingrn_, and expires after 30 days. It is shown once — copy it before leaving the page. The backend stores only the token’s metadata (label, creation date, expiry), never its value, so a lost token must be regenerated rather than recovered.

4. Configure the CLI

The CLI reads its settings from a user-level conf.toml. Print its path:

ingrain config

That command prints the path; open the file in your own editor. The location depends on your platform: ~/.ingrain/conf.toml by default, $XDG_CONFIG_HOME/ingrain/conf.toml if that variable is set, or %APPDATA%\ingrain\conf.toml on Windows.

Open the file and add a [context] section holding your platform’s sync URL and the token from step 3:

[context]
syncUrl = "https://app.ingrainlabs.dev/ingrain-agent-sync"
ingrainApiToken = "ingrn_..."

Only the user-level file counts

ingrain context takes syncUrl and ingrainApiToken from two places: the user-level conf.toml — the path ingrain config prints — and the INGRAIN_SYNC_URL and INGRAIN_API_TOKEN environment variables, which override the file. A project-local conf.toml is ignored for these two keys by design, so cloning a repo can never aim your token at someone else’s syncUrl.

Both keys must sit under the [context] header — TOML scopes keys to the header above them, so a syncUrl written anywhere else is a different key. If either one is missing, ingrain context stops with an error telling you what to set.

Verify the whole chain end to end:

ingrain context security_rules "authentication" --limit 3

Rules coming back means the plugin will find them too. See the [context] configuration reference and the context command for the full set of options.

Sandbox permissions

The plugin makes exactly one outbound call: a read-only ingrain context security_rules lookup against your syncUrl, when it proposes mitigations. If your coding agent runs under a sandbox that restricts command execution or network access, allow that ingrain context command to run and to reach your syncUrl host.

Upgrade

Once installed, the CLI manages its own upgrades:

ingrain upgrade

This re-fetches the latest release through the same install proxy. See the upgrade command for flags, and the [upgrade] config section for customising the proxy URL.

Uninstall

ingrain uninstall

Removes the ingrain binary and its PATH entry. Your ~/.ingrain/ directory is preserved — conf.toml and any session data survive a reinstall, so your settings carry over. Delete it by hand for a clean wipe. See the uninstall command for flags.

Troubleshooting

• ingrain: command not found after install — the installer wrote the binary to your install dir but the shell hasn’t picked it up. Open a new shell or source your profile.

Next steps

• Browse the full command reference.
• Tune defaults via Configuration.