agentself

agentself gives an agent a persistent local identity: a wallet, encrypted secrets, and optional email. It is a CLI first, with one command tree across the supported backends.

Linux, macOS, and Windows. Python 3.11+. This is the first public alpha, so review COMPATIBILITY.md before automating against it.

Install

uv tool install agentself

Or:

pipx install agentself

Quick start

agentself install --tools
agentself init
agentself wallet address
agentself secret create API_TOKEN --file ./api-token.txt
agentself email connect

init creates one identity directory. Run agentself show to inspect it; repeat init is safe, and --force is required to change an existing identity or its backends. Email setup is optional and does not block init.

Commands

Use the CLI for the exact current flags and input rules:

agentself --help
agentself wallet --help
agentself email --help

Backends & configuration

Backends keep the public commands stable while allowing the implementation to change:

agentself backends
agentself backends wallet
agentself backends email
agentself backends store

Choose a backend during initialization:

agentself init --wallet ethereum --email imap --store pass

Wallet and email backends can also be selected with AGENTSELF_WALLET_BACKEND and AGENTSELF_EMAIL_BACKEND. The precedence is CLI flag, environment variable, saved identity configuration, then default; there is no automatic failover. Backend-specific setup, credential sources, and required host settings are exposed by agentself backends and agentself email connect.

The identity directory is ~/.agentself by default. Set AGENTSELF_IDENTITY_DIR to isolate identities, for example:

AGENTSELF_IDENTITY_DIR=~/.agent-a agentself init
AGENTSELF_IDENTITY_DIR=~/.agent-b agentself init

Use AGENTSELF_EMAIL_ADDRESS and AGENTSELF_EMAIL_CREDENTIAL for transient email configuration when appropriate. Runtime environment credentials are not copied into the identity; complete email connect with its secure result file when the credential should be encrypted into the identity.

Automation and agents

The CLI is designed to be discovered from a shell. No MCP server or Python import is required:

agentself --help
agentself backends
agentself diagnose

For automation, prefer --json. Successful and failed commands emit one JSON object; human-readable errors stay on stderr. Exit codes are 0 for success, 1 for an error, 2 for a refusal, and 3 when an input, dependency, or resource is missing. agentself --json --version reports the package version and machine-output schema version. Consumers should ignore unknown JSON keys.

An optional bundled skill provides the same discovery guidance to compatible coding agents:

agentself install --skills
agentself install --skills -g

Security

• Secret values are encrypted at rest by the configured store.
• Secret listings return names, not values; wallet.key requires --unsafe to export.
• Logs and structured errors redact secret values.
• Missing credentials and host tools fail instead of silently switching backends.
• Wallet backends are live; wallet send can move real assets.
• Identity files are replaced atomically, and wallet-send retries do not create a second payment.

Back up an identity with agentself backup PATH. Report vulnerabilities through SECURITY.md.

Extending agentself

New backends implement the existing channel contract and do not add provider-specific CLI verbs. See CONTRIBUTING.md.

Development

git clone https://github.com/agentself/agentself
cd agentself
uv sync
uv run pytest
uv run ruff check .
uv run mypy agentself

See RELEASE.md for the small-project release checklist.

License

MIT