walleterm

Your agent asks. 1Password signs. A small macOS signing companion for agents that use Stellar and 1Password.

Website · Documentation · Contributing

walleterm lists public Ed25519 keys and signs Stellar artifacts through the 1Password desktop SSH agent. It accepts a transaction, an authorization preimage or entry, or a SEP-53 message. It computes the digest itself. It verifies each signature before it returns the signature. The private key stays in 1Password. walleterm tunnel also lets a connected website request signatures on one Stellar network. walleterm is one Rust binary. It embeds the demo website and needs no JavaScript runtime.

Status and safety

walleterm is experimental, open-source software from the Stellar Development Foundation (SDF) and is not production-ready. It is not a wallet: it does not store keys or assets. SDF does not control the Stellar network and never holds your keys or assets. walleterm asks your 1Password app to sign with a key stored there. 1Password does not show the transaction details. An AI agent you connect can request and approve signatures that move real assets. Website connections run through Cloudflare, which can see request data. Use a dedicated key, review each transaction before you approve it, and use walleterm at your own risk. Provided as-is under the Apache 2.0 license.

Walleterm is before version 1.0. Interfaces can change without notice.

• 1Password shows the application and the key. It does not show the network, amount, destination, or contract policy. Review each artifact before you sign it. Cached 1Password approval can permit later signatures without a prompt. To prevent this, ask for approval of each signature.
• Walleterm checks each artifact before it asks 1Password to sign. Other programs can use the 1Password SSH agent directly. 1Password approval applies to them too. See the security model.
• Use dedicated wallet keys. A shared SSH key can also authorize other systems.
• The website bridge signs for one network. On testnet, futurenet, and a local network, a connected website approves its own requests, unless the tunnel runs with --approve. On mainnet and custom networks, you or your agent approve each request with walleterm approve.
• Walleterm supports Ed25519 keys only. A contract account needs its exact authorization adapter.

Install

You need an Apple silicon Mac with macOS 13 or later. Turn on the SSH agent in the 1Password desktop app.

curl -fsSL https://walleterm.com/install.sh | sh
npx skills add stellar-experimental/walleterm -g

The script installs walleterm and its stellar-walleterm alias into ~/.local/bin. It does not use sudo. It checks the release checksum and the Developer ID team before it replaces the command. Run it again to update. Set WALLETERM_INSTALL_DIR for another directory, or WALLETERM_VERSION=0.2.0 for one release. The script is site/install.sh. Read it before you run it. npx skills add installs the walleterm signing skill and the walleterm-site-bridge website skill for your agents.

You can also install with Homebrew. The cask also installs cloudflared. Update with brew upgrade --cask walleterm.

brew tap stellar-experimental/walleterm https://github.com/stellar-experimental/walleterm
brew install --cask stellar-experimental/walleterm/walleterm

Install these tools too:

• The Stellar CLI builds, inspects, and submits transactions: brew install stellar-cli.
• walleterm tunnel and walleterm demo need cloudflared: brew install cloudflared.
• The 1Password CLI is optional. Only walleterm tunnel --vault needs it: brew install --cask 1password-cli.

Generate an Ed25519 SSH key inside the 1Password desktop app. Enable that item in the 1Password SSH agent. Then run walleterm list --human to see its public G-address. Connected websites can see your 1Password key names. Use generic names that don't include personal information.

Ask for approval of each signature

By default, 1Password approves an application and all of its subprocesses. The approval lasts until 1Password locks. After one approval, an agent can sign again without a prompt. You can change this in 1Password:

1. Open Settings > Developer in the 1Password desktop app, then open the SSH agent advanced settings.
2. Set Ask approval for each new to request.

1Password then asks for approval of every signature and remembers no approval. The prompt still shows only the process and the key. Review the artifact before you approve it. This setting applies to every key in the SSH agent. SSH logins and Git signing then ask for each request too.

Two settings give less protection with fewer prompts. Ask approval for each new set to application and terminal session limits an approval to one terminal tab. Remember key approval can end an approval after 4, 12, or 24 hours. See the 1Password authorization settings.

Sign from an agent

unsigned=$(stellar tx new payment --network testnet --source-account G... --destination G... --amount 10000000 --build-only)
printf '{"public_key":"G...","network_passphrase":"Test SDF Network ; September 2015","transaction_xdr":"%s"}' "$unsigned" | walleterm sign

The --amount value is in stroops. 10000000 stroops is 1 XLM. A transaction result contains signed_transaction_xdr: the same envelope with one more signature. Each success also returns the public key, the digest, the signature, and verified: true. A failure returns JSON with a stable error code and a nonzero exit status. See the CLI interface for the four input shapes and the Stellar CLI guide for the full pipeline.

Connect a website

Run the bridge in one terminal and the example website in another:

walleterm tunnel --vault Private
walleterm demo

1. The tunnel shows a public URL, an eight-digit connection code, and a QR code.
2. Open the demo URL, or scan the demo QR code with your phone.
3. Select Connect Walleterm. Select Scan tunnel QR code, or type the tunnel URL and code.
4. Select a dedicated testnet wallet. Create a request in the demo, review it, and select Sign.
5. Approve the 1Password prompt on the Mac if it appears. The demo submits the transaction to testnet.

--vault limits the website wallets to one 1Password vault. Omit it to offer all Ed25519 agent keys. See the website bridge guide for setup, recovery, and website integration.

Documentation

Document	Contents
INTERFACE.md	The list and sign commands: input shapes, output, errors, and limits
STELLAR-CLI.md	Build, sign, and submit with the Stellar CLI. Digest and JSON reference
WEB-BRIDGE.md	Run and operate walleterm tunnel and walleterm demo
BRIDGE-PROTOCOL.md	The bridge HTTP routes, request kinds, and errors
SEP-43.md	The browser SDK, its SEP-43 wallet, and the Stellar Wallets Kit module
CONNECTION-UI.md	The website connection component
CONNECTION-LIFECYCLE.md	Signing deadlines and public tunnel recovery
DEMO.md	The demo website
CONTRACT-AUTHORIZATION.md	Contract account authorization in the demo
OPENZEPPELIN.md	The OpenZeppelin smart account adapter
AGENTIC-PAYMENTS.md	x402 and MPP compatibility
KEY-STORES.md	Research on key stores beside 1Password: Apple, hardware keys, and password managers
SECURE-ENCLAVE.md	Design notes for a Secure Enclave P-256 signer for smart accounts
PRIVY-WALLET.md	Research that compares walleterm with a Privy-backed Stellar wallet for agents
STELLAR-CLI-AGENTS.md	Research that compares walleterm with the Stellar CLI for Agents docs
NETWORKS.md	Network restrictions, hard-coded limits, and the plan for mainnet and custom networks
LIVE-TESTS.md	Live 1Password and testnet tests
MAINTAINING.md	Releases, the Homebrew cask, and the website

The signing skill and the site bridge skill give agents the workflows.

Verified coverage

Live testnet runs passed with dedicated 1Password keys. They covered classic multisig, fee bumps, contract accounts, and the OpenZeppelin adapter. They also covered SEP-53 messages and the SEP-43 wallet through the Stellar Wallets Kit. Fixture runs covered CAP-71 address-bound authorization and CAP-85. See the evidence index for each record, its revision, and its limits.

Develop

See CONTRIBUTING.md to build from source, run the checks, and link the skills.

License and security

Walleterm uses the Apache License 2.0. Report a vulnerability as SECURITY.md describes. Do not open a public issue for it.