Quickstart · local machine

Your first session through Torana.

You need Git, Go 1.26.6 or newer, and a provider API credential. This example uses DeepSeek; your normal provider usage is still billed by your provider.

Run Torana locally, keep the listener on loopback, and review each plugin’s requested capabilities before enabling it.

1. Install

git clone https://github.com/torana-edge/torana-edge.git
cd torana-edge
go build -o ./torana ./cmd/torana
cp config.example.json config.json

This walkthrough currently builds the development source. To reproduce a particular revision, check out its reviewed commit SHA before building. The first tagged release will get its own verified install instructions.

2. Start without plugins

export TORANA_DATA_DIR="$PWD/.torana-data"
./torana --debug

This keeps evaluation state in .torana-data inside the checkout. On first run Torana imports config.json; later changes belong in the local control plane, not the seed file. This directory can contain credentials and plugin files: keep it private. Open http://127.0.0.1:8080/_torana/ to inspect activity or edit providers. The listener and control plane default to loopback. Leave the server running, then verify it from another terminal:

curl --fail-with-body --silent http://127.0.0.1:8080/health

A healthy process returns {"status":"ok"}. A failed plugin reload keeps the last known-good pipeline serving but reports a degraded health status.

3. Send one inference request

export DEEPSEEK_API_KEY='replace-with-your-deepseek-key'

curl --fail-with-body --silent \
  http://127.0.0.1:8080/provider/deepseek/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: Torana works"}]}'

This uses the built-in DeepSeek route and forwards your caller credential only to that selected provider. Configure a different provider in the control plane if you do not use DeepSeek.

4. Point your harness at it

export OPENAI_BASE_URL=http://127.0.0.1:8080/provider/deepseek/v1

Replace deepseek with the provider name in your configuration. The harness must speak that provider’s supported wire format; see the exact endpoint and harness matrix. Auxiliary provider endpoints pass through without entering the plugin pipeline.

5. Add one useful plugin

In a second terminal, from your Torana checkout, install the usage logger:

./torana plugin install https://github.com/torana-edge/torana-plugins/tree/main/plugins/usage_logger

Installation builds the plugin but does not approve or enable it. In the local control plane, inspect its requested capabilities and private-file budget, approve and enable it, and verify it is in the active pipeline. Send another request, then read the result:

tail -F "$(./torana plugin file path usage_logger usage.jsonl)"

Each JSONL record includes provider, model, latency, status, and reported input/output/cache token counts. It does not contain prompts, responses, or headers. You now have a concrete check that requests are reaching Torana and the plugin is running.

Next, explore the other plugins or write your own.

Switch back whenever you want

Restore your harness’s previous provider/base-URL configuration and restart the harness. If OPENAI_BASE_URL was previously unset, use unset OPENAI_BASE_URL in that shell. Once your agent connects directly again, stop Torana with Ctrl+C. The evaluation directory remains on disk until you remove it.

Help improve the next release

Tell us how your session went: your Torana and harness versions, provider/endpoint, whether streaming and tool calls worked, and the first confusing step. Keep credentials, private source, and sensitive prompts out of your report.