Quickstart · local machine

Your first session through Torana.

Install Torana, connect the coding harness you already use, then add a plugin. Keep your existing login; your provider’s normal usage limits and billing apply.

1. Install Torana

macOS or Linux:

curl -fsSL https://torana.sh/install.sh | sh

$installer = Join-Path $env:TEMP ("torana-install-" + [guid]::NewGuid() + ".ps1")
Invoke-WebRequest https://torana.sh/install.ps1 -OutFile $installer
& $installer
Remove-Item -LiteralPath $installer

The installer selects your platform and verifies the release checksum. It does not start Torana. Release notes and direct downloads · Build from source.

2. Start without plugins

torana --debug start --port 8143
torana status

Choose any free port. Torana runs in the background and creates its managed configuration in your platform’s user-config directory. No checkout, seed file, or TORANA_DATA_DIR export is needed. Keep this directory private: it can contain credentials and plugin files. Run torana open to inspect activity or edit providers. The CLI resolves the running instance’s port for later commands. Verify the live endpoint:

curl --fail-with-body --silent "$(torana endpoint)/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. Which harness do you use?

Pick one route. You do not need to configure every provider. Connecting to a different API format? Use an API bridge.

Claude Code

Already signed in? Keep the default anthropic provider on Use harness credentials, then launch Claude Code with a command-scoped address:

ANTHROPIC_BASE_URL="$(torana endpoint anthropic)" claude

Do not add a DeepSeek key or replace your login. If your shell already sets an Anthropic key/token or your Claude configuration uses a key helper, that credential may take precedence. The Claude Code guide explains the distinction.

for name in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN; do
  if printenv "$name" >/dev/null; then
    printf '%s is set\n' "$name"
  fi
done

Codex, pi, oh-my-pi, OpenCode, or Antigravity

Keep your usual harness and follow its recipe in the setup guide. Choose the Codex recipe for your ChatGPT login or API key; for Antigravity, the guide connects your existing Google login through Torana’s local TLS ingress.

Using Codex with plugins? Follow the guide’s HTTP/SSE configuration (supports_websockets = false) so response hooks and usage logging run. For Antigravity, start interactively to approve tool actions, or follow its guide for a single headless task with explicit permissions.

Ask your harness to read a small, non-sensitive file. Open the local control plane’s Live Feed to see the request, model, and status. Next, add a plugin below: try a local-model check, or start with usage logging or a deterministic guard.

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

curl --fail-with-body --silent \
  "$(torana endpoint 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"}]}'

torana feed
torana stats

Find the matching request in the feed. You can also inspect it in the local UI. torana status reports the instance and log path.

4. Add your first plugin

Install a maintained plugin by name—no Git or Go needed. Torana downloads and verifies its release bundle; you choose its permissions before enabling it.

Torana plugins run in the request and response path. With permissions you approve, they can inspect or change a request or response, block it, or call another endpoint before the workflow continues. That endpoint can be a local model: your coding agent can keep using its hosted model while a focused local model handles a narrow job. Combining the two unlocks useful workflows without moving the whole session to a local model.

Have a local model, or comfortable setting up a small one?

Starting from scratch? Follow the local-model PII walkthrough for a model download, setup steps and the measured trade-offs.

Try pii first. A focused local model working alongside your hosted coding agent is the clearest way to see what Torana plugins unlock. This plugin asks your OpenAI-compatible local model to check new tool output before it reaches the primary model. Detection depends on the scanner you choose; this is an extra check, not a guarantee.

Register your local model first. Run torana open, open Settings, and choose Add provider:

• Provider name: local-scanner.
• Upstream URL: your model server's address, such as http://127.0.0.1:8081/v1 for an OpenAI-compatible local server or http://127.0.0.1:11434 for Ollama. Use your server's actual port.
• Provider format: openai. Authentication: No authentication for an unauthenticated local server.
• Plugin model defaults → Default model: enter your loaded model's ID if the server requires one (for Ollama, its model name). Single-model servers that accept requests without a model can leave this blank. Leave Inference path override blank.

Choose Save settings, then install the plugin:

torana plugin install pii

Open the control plane again with torana open. Choose Pipeline, open the installed pii plugin, and find Resource bindings and limits → scanner → Provider. Select the local-scanner provider you saved in Settings. Torana derives the normal inference path. If the dropdown is empty, check that you saved the provider with format openai and authentication No authentication; plugins make their own model calls and cannot use your harness's login.

The model-backed PII guide has the complete CLI configuration and approval document. Eligible tool output goes to the scanner you bind; keep that binding local if you do not want an additional remote model call.

Don’t have a local model running?

Start with either of these—no local model needed.

See your usage with usage_logger. Record content-free request, latency and token-usage data:

torana plugin install usage_logger

It does not record prompts or tool output, and it does not block secrets. The usage logger guide covers its CLI setup and recorded fields.

Check recognizable secrets with pii_guard. Use deterministic checks for common secret shapes:

torana plugin install pii_guard

pii_guard makes no model or network calls. Review its requested tool-result and state permissions before enabling it. Its setup guide also covers the CLI path. You can use either plugin alone; for broader protection, run both with pii_guard first.

Enable the plugin

Run torana open, choose Pipeline, and open the plugin you installed. Review its digest and requested permissions. For pii, also confirm the scanner binding and model-call limits; for usage_logger, review the bounded usage-file storage. Choose Approve & enable. Installation alone does not enable a plugin, and a rebuilt bundle needs a new approval.

Test usage_logger

If you chose usage_logger, ask your routed harness to read a small, non-sensitive file. Then inspect the latest content-free records using your shell’s tail:

tail -n 5 "$(torana plugin file path usage_logger usage.jsonl)"

Torana resolves the file path; your shell reads it. Look for the request’s provider, latency and reported token counts. You can also see the request in Live Feed. Continue to other plugins whenever you like.

Test pii or pii_guard

For either protection plugin, create a file containing an obviously synthetic credential. Do not use a real key:

echo 'PAYMENT_API_KEY=sk_test_torana_demo_not_a_real_key_123' > demo-sensitive.txt

In the coding harness you routed through Torana, enter:

Read the demo-sensitive.txt file in this directory and tell me what it contains.

The harness reads the file locally and includes the tool result in its next model request. When a scan finds sensitive content, Torana replaces the result with a recoverable error: Tool output withheld from pii, or Sensitive output withheld from pii_guard. The request continues to the primary provider without that value, so the agent can acknowledge it and move on. You can inspect the request’s status in Torana’s Live Feed.

With pii_guard first, this obvious value is replaced with a value-free tool error before the contextual scan. With only pii, the local scanner decides it. The scanner still checks other failed tool results because failures can contain secrets. After the check, remove the test file:

rm demo-sensitive.txt

Next, explore the other plugins or write your own.

Switch back whenever you want

Exit the harness and launch it normally. The command-scoped Claude Code example does not change your saved settings or later shell commands. If you edited a harness configuration file, restore its previous settings. Once your agent connects directly again, stop Torana with torana stop --yes. Use torana serve if you prefer foreground serving. Your managed settings and plugin state remain available for the next session.

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.