Native library reference. Extended CLI examples use
jacs-compat. This source reference can include unreleased changes; see the package guide for installation and MCP profiles for available tools.
Quick Start Guide
Get a persistent agent identity, sign data, and verify it.
Start with MCP
Install the portable CLI and start its default verification-only MCP server:
cargo install jacs-cli --locked
jacs mcp
{
"mcpServers": {
"jacs": { "command": "jacs", "args": ["mcp"] }
}
}
Verification requires independently trusted public evidence. A valid signature proves integrity under that key; your application decides identity and authority.
Portable CLI
Create an encrypted identity, sign JSON and verify with the exported public identity:
mkdir -m 700 .jacs
jacs create --output .jacs/agent.json > public-identity.json
printf '%s' '{"message":"hello"}' | jacs sign --agent .jacs/agent.json --input - > signed.json
jacs verify --public-identity public-identity.json --input signed.json
The terminal prompts for the password. For an MCP client that can provide the
host's configured secret source, explicitly enable signing with
jacs mcp --profile local-sign --agent /absolute/path/to/.jacs/agent.json.
Use the same arguments in its mcpServers configuration. See the
current MCP guide
for secret handling and the available tools.
The remaining native examples use a separate installation:
cargo install jacs-cli-compat --locked
jacs-compat quickstart --name my-agent --domain my-agent.example.com
This creates jacs.config.json and persistent native keys for direct libraries
and extended text/image commands. The native MCP profiles use jacs-compat mcp;
see extended profiles.
Python
python -m pip install jacs==0.16.1
import jacs.simple as jacs
info = jacs.quickstart(name="my-agent", domain="my-agent.example.com")
signed = jacs.sign_message({"action": "approve", "amount": 100})
result = jacs.verify(signed.raw)
print(f"Valid: {result.valid}, Signer: {result.signer_id}")
Node.js
Source and published packages: Version 0.16.1 has a recorded release inventory. Version 0.16.0 is the first release whose source includes the native PQ DID/JWK and Agent Card behavior. See the identity integration guide.
npm install --save-exact @hai.ai/jacs@0.16.1
import * as jacs from '@hai.ai/jacs/simple';
await jacs.quickstart({
name: 'my-agent',
domain: 'my-agent.example.com',
});
const signed = await jacs.signMessage({ action: 'approve', amount: 100 });
const result = await jacs.verify(signed.raw);
console.log(`Valid: ${result.valid}, Signer: ${result.signerId}`);
Sign Markdown or text
jacs-compat sign-text README.md
jacs-compat verify-text README.md
jacs-compat verify-text --strict README.md
sign-text appends a -----BEGIN JACS SIGNATURE----- block at the end of the file. The original content remains readable and can be counter-signed by another agent.
See Inline Text Signatures for multi-signer flows, strict mode, and --key-dir.
Sign images
jacs-compat sign-image photo.png --out signed.png
jacs-compat verify-image signed.png
jacs-compat extract-media-signature signed.png
JACS embeds the signature in PNG, JPEG, or WebP metadata. See Image and Media Signatures for overwrite policy, robust mode, and verification details.
Native password bootstrap
Choose one explicit password source for jacs-compat: the host-provided
JACS_PRIVATE_KEY_PASSWORD, or JACS_PASSWORD_FILE pointing to a protected
secret file. Setting both is an error. When neither is set, the native CLI can
use the OS keychain; see password and keychain setup.
Python and Node quickstart can generate a password in-process. Retain it through your host secret source for later processes; see the language quickstart guide.
Algorithm
The default signing algorithm is pq2025 (ML-DSA-87 / FIPS-204). Use the
user-facing ed25519 choice if you need a smaller classical signature. JACS
stores and emits the canonical Ed25519 wire label as ring-Ed25519:
jacs-compat quickstart --name my-agent --domain my-agent.example.com --algorithm ed25519