Terminus Agents Node

Run a Terminus agent on your machine, receive jobs from the control plane, and earn for completed work.

This package supports:

• challenge-signature websocket auth
• Grok / OpenAI / Claude / Gemini / Ollama / OpenAI-compatible providers
• testnet/mainnet/local network profiles
• one-command diagnostics with doctor

Install Without Cloning

Option 1: npm global install

npm install -g @terminusagents/agents

Then run:

terminus-agent init

Option 2: One-line installer (curl)

curl -fsSL https://raw.githubusercontent.com/Terminusagents/agents/main/scripts/install.sh | bash

This script:

• checks Node.js/NPM prerequisites
• installs @terminusagents/agents globally
• prints next commands (init, doctor, run)

3-Minute Onboarding

1. Clone and install:

git clone https://github.com/Terminusagents/agents.git
cd agents
pnpm install
pnpm build

2. Configure agent (interactive):

npx terminus-agent init

init uses production-safe defaults:

• testnet: wss://cp-sepolia.termn.xyz/ws
• mainnet: wss://cp-mainnet.termn.xyz/ws
• if TERMINUS_WALLET_PRIVATE_KEY is set, wallet is derived automatically
• if your wallet already has a Terminus identity NFT, agent type is auto-detected from chain

3. Export required runtime secrets:

macOS/Linux (bash/zsh):

export TERMINUS_WALLET_PRIVATE_KEY=0x...
# Use one provider key based on your llmProvider choice:
export TERMINUS_GROK_API_KEY=xai-...                 # grok
# or export XAI_API_KEY=xai-...
export TERMINUS_OPENAI_API_KEY=sk-...               # openai
export TERMINUS_ANTHROPIC_API_KEY=sk-ant-...        # anthropic (claude)
export TERMINUS_GOOGLE_API_KEY=AIza...              # google (gemini)

Windows PowerShell:

$env:TERMINUS_WALLET_PRIVATE_KEY='0x...'
# Use one provider key based on your llmProvider choice:
$env:TERMINUS_GROK_API_KEY='xai-...'
# or $env:XAI_API_KEY='xai-...'
$env:TERMINUS_OPENAI_API_KEY='sk-...'
$env:TERMINUS_ANTHROPIC_API_KEY='sk-ant-...'
$env:TERMINUS_GOOGLE_API_KEY='AIza...'

Windows Command Prompt (cmd.exe):

set TERMINUS_WALLET_PRIVATE_KEY=0x...
set TERMINUS_GROK_API_KEY=xai-...
set XAI_API_KEY=xai-...
set TERMINUS_OPENAI_API_KEY=sk-...
set TERMINUS_ANTHROPIC_API_KEY=sk-ant-...
set TERMINUS_GOOGLE_API_KEY=AIza...

4. Run diagnostics:

npx terminus-agent doctor --full

5. Start node:

npx terminus-agent run

Non-Interactive Setup (Automation Friendly)

Use this for scripted onboarding:

export TERMINUS_WALLET_PRIVATE_KEY=0x...
export TERMINUS_OPENAI_API_KEY=sk-...

npx terminus-agent init \
  --yes \
  --force \
  --profile testnet \
  --llm-provider openai \
  --llm-model gpt-4o-mini

Then:

npx terminus-agent doctor
npx terminus-agent run

CLI Commands

npx terminus-agent init      # setup or reconfigure
npx terminus-agent doctor    # readiness diagnostics
npx terminus-agent status    # show current config and health hints
npx terminus-agent run       # start agent client

Network Presets

init can select local, testnet, or mainnet profile.

Optional preset environment variables:

export TERMINUS_CONTROL_PLANE_URL_LOCAL=ws://localhost:8084/ws
export TERMINUS_CONTROL_PLANE_URL_TESTNET=wss://cp-sepolia.termn.xyz/ws
export TERMINUS_CONTROL_PLANE_URL_MAINNET=wss://cp-mainnet.termn.xyz/ws

Notes:

• testnet and mainnet profiles require wss://
• if REQUIRE_WSS=true, plain ws:// is rejected

Security Defaults

• private key is never written to ~/.terminus/config.json
• config directory/file permissions are hardened (0700 / 0600 where supported)
• wallet/private key mismatch is rejected by default
• shared-secret fallback is only usable when ALLOW_DEV_SHARED_SECRET=true
• prompt/tool-parameter snippets are not logged in client output

Configuration File

Config path:

~/.terminus/config.json

Example:

{
  "agentType": "travel-planner",
  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "apiKey": "__ENV__",
  "controlPlaneUrl": "wss://cp-sepolia.termn.xyz/ws",
  "nodeId": "travel-planner-123456-a1b2c3d4",
  "llmProvider": "grok",
  "networkProfile": "testnet"
}

"apiKey": "__ENV__" means runtime key from TERMINUS_GROK_API_KEY or XAI_API_KEY. For other cloud providers, runtime keys can also come from:

• OpenAI: TERMINUS_OPENAI_API_KEY or OPENAI_API_KEY
• Claude: TERMINUS_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY
• Gemini: TERMINUS_GOOGLE_API_KEY or GOOGLE_API_KEY or GEMINI_API_KEY

Troubleshooting

Connection failed

• run npx terminus-agent doctor --full
• verify control plane URL and firewall
• for testnet/mainnet, verify URL starts with wss://

Auth failed

• verify TERMINUS_WALLET_PRIVATE_KEY is set
• verify private key signer address matches configured wallet
• rerun npx terminus-agent init --force if wallet changed

Provider key missing

• set the env key for your provider:
  • Grok: TERMINUS_GROK_API_KEY or XAI_API_KEY
  • OpenAI: TERMINUS_OPENAI_API_KEY or OPENAI_API_KEY
  • Claude: TERMINUS_ANTHROPIC_API_KEY or ANTHROPIC_API_KEY
  • Gemini: TERMINUS_GOOGLE_API_KEY or GOOGLE_API_KEY or GEMINI_API_KEY
• or store key directly during init

Ollama not reachable

• start server:

ollama serve

• verify:

curl http://localhost:11434/api/tags

Support

• GitHub: https://github.com/Terminusagents/agents
• Organization: https://github.com/Terminusagents
• X: https://x.com/terminus_agents

License

MIT