docs

Getting started

RalphTerm is a local Rust daemon that launches official AI CLIs inside real PTYs and exposes an API for orchestration.

Install from source

git clone git@github.com:RayforceDB/ralphterm.git
cd ralphterm
cargo build --release

Start the daemon

cargo run -- serve --bind 127.0.0.1:7878

Health check

curl http://127.0.0.1:7878/health
# {"ok":true}

Deterministic smoke test

Use a shell command override before testing real agents.

cat > /tmp/ralphterm-smoke.json <<'JSON'
{
  "agent": "claude",
  "command": "/bin/sh",
  "args": ["-lc", "read line; printf '%s\n' "$line"; echo COMPLETED"],
  "prompt": "hello from ralphterm"
}
JSON

ID=$(curl -sS -X POST http://127.0.0.1:7878/v1/sessions \
  -H 'content-type: application/json' \
  --data-binary @/tmp/ralphterm-smoke.json \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')

curl http://127.0.0.1:7878/v1/sessions/$ID
curl http://127.0.0.1:7878/v1/sessions/$ID/transcript

Real agent sessions

Install and authenticate the official CLI first. RalphTerm does not own provider credentials.

claude auth login
codex login

curl -sS -X POST http://127.0.0.1:7878/v1/sessions \
  -H 'content-type: application/json' \
  -d '{"agent":"claude","prompt":"Say hello and end with COMPLETED"}'