Set Up Trit With an Agent

This document is an instruction contract for a coding agent setting up Trit on a user’s machine. Follow it in order. Do not install, edit configuration, enable services, or expose a network endpoint until the user has answered the setup questions and approved the plan.

Safety rules

• Treat Trit as privileged developer tooling: its agents and terminals run as the Trit service user and can access configured project roots.
• Run Trit as a normal, dedicated user when practical. Do not install or run it as root.
• Never expose Trit’s origin port directly to the public Internet.
• Do not use sudo unless a missing host dependency or user-service persistence requires it, and obtain approval for the exact command first.
• Never put API keys, access tokens, passwords, or other credentials in config.yaml. Put secrets in ~/.config/trit/env with mode 0600, then reference their variable names with envFrom where needed.
• Preserve existing Trit configuration and data. Back them up before changing an existing installation.
• Use the stable installer only after the user approves the final plan. Do not execute an installer directly from a pipe; download it, inspect it, and then run the reviewed file.

1. Inspect the host

Perform read-only checks and summarize the results:

id -un
uname -s
uname -m
getconf GNU_LIBC_VERSION 2>/dev/null || true
command -v curl tar sha256sum bwrap systemctl tmux npx uvx trit || true
systemctl --user show-environment >/dev/null 2>&1; printf 'systemd-user=%s\n' "$?"
loginctl show-user "$USER" -p Linger 2>/dev/null || true

Trit’s release installer currently supports glibc-based Linux on x64 and ARM64. It requires curl, tar, sha256sum, and Bubblewrap (bwrap). A normal production install expects a working systemd user manager. tmux, npx, and uvx are optional and depend on the chosen terminal backend and agents.

Also inspect existing state without printing secret values:

command -v trit >/dev/null && trit version || true
command -v trit >/dev/null && trit paths || true
systemctl --user is-enabled trit.service 2>/dev/null || true
systemctl --user is-active trit.service 2>/dev/null || true
test -f "$HOME/.config/trit/config.yaml" && printf '%s\n' 'existing Trit config found'
test -f "$HOME/.config/trit/env" && printf '%s\n' 'existing Trit environment found'
test -f "$HOME/.local/share/trit/trit.db" && printf '%s\n' 'existing Trit database found'

Do not display ~/.config/trit/env or other credential files in chat or logs.

2. Ask the user

Ask these questions before proposing changes. Prefer a short numbered list and explain any detected defaults.

1. Which existing absolute directories may Trit use as project roots? Recommend the narrowest practical roots; do not allow /, the entire home directory, or directories containing unrelated sensitive data.
2. Which ACP agents should be available, and which corresponding CLIs are already installed and authenticated? Record whether each agent should use an ACP Registry distribution (npx or uvx) or an existing local command.
3. Should Trit be local-only, reached through SSH port forwarding, or remotely available through Cloudflare Tunnel and Access? Recommend local-only for the first setup.
4. Should interactive terminals use pty or tmux? Recommend pty unless terminal sessions must survive Trit service restarts. Confirm that tmux is installed before selecting it.
5. Should the user service continue running after logout? If yes and lingering is disabled, explain that enabling it may require an administrator.
6. Is this a fresh installation or an upgrade/migration whose existing configuration and database must be retained?
7. Should voice input (speech-to-text) be enabled? If yes, ask which supported API provider to use, whether they prefer batch or streaming transcription, their language(s), and any project vocabulary. Explain that audio is sent to the selected provider, provider billing and retention terms apply, and an ACP CLI or consumer subscription does not provide an API credential.
8. Should read-only thread sharing be enabled? If yes, ask whether the owner needs link-only shares, email-restricted shares, or both. Recommend a separate share hostname and loopback listener. Explain that shares include the complete visible thread history, including reasoning and activity; that live views include later history; and that email restriction requires a dedicated Cloudflare Access application audience.

Do not ask for secret values in chat. If a selected agent needs credentials, ask the user to authenticate its CLI directly or arrange for the credential to be written locally to the mode-0600 environment file without echoing it.

3. Present the plan

Before making changes, present a concrete plan containing:

• Missing host packages and the exact proposed package-manager command, if any
• The install or upgrade path
• Every project root that will be allowed
• Each agent and how Trit will launch it
• The terminal backend
• The access mode and listen address
• Whether user lingering or a Cloudflare Tunnel/Access configuration is in scope
• Whether voice input will be enabled and, if so, the speech-to-text provider type, credential environment variable, languages, and batch or streaming mode
• Whether read-only thread sharing will be enabled and, if so, its hostname, loopback port, link types, expiration expectations, and dedicated Cloudflare Access application audience
• Existing paths that will be backed up and files that will be edited
• The verification commands that will run

Wait for explicit confirmation.

4. Preserve existing state

For an existing install, first record trit version and trit paths. Create a timestamped private backup directory outside the paths being changed:

timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
backup_dir="${XDG_STATE_HOME:-$HOME/.local/state}/trit/backups/agent-setup-$timestamp"
install -d -m 700 "$backup_dir"
test -f "$HOME/.config/trit/config.yaml" && install -m 600 "$HOME/.config/trit/config.yaml" "$backup_dir/config.yaml"
test -f "$HOME/.config/trit/env" && install -m 600 "$HOME/.config/trit/env" "$backup_dir/env"
command -v trit >/dev/null && test -f "$HOME/.local/share/trit/trit.db" && trit backup "$backup_dir/trit.db"

Respect custom paths reported by trit paths or environment configuration instead of assuming the defaults. Do not overwrite an existing config with the installer’s example. Update it minimally and preserve comments when possible.

5. Install the beta release

Download and inspect the installer before execution:

installer="$(mktemp)"
curl -fsSL https://trit.wtf/install -o "$installer"
sed -n '1,$p' "$installer"
bash -n "$installer"
bash "$installer"
rm -f "$installer"

If no beta public artifacts exist yet, stop and tell the user that the installer cannot complete until downloads.trit.wtf provides trit-linux-x64.tar.gz or trit-linux-arm64.tar.gz plus SHA256SUMS. Do not substitute an unreviewed branch archive.

The installer does not use sudo. By default it creates:

6. Configure Trit

Edit ~/.config/trit/config.yaml to contain only approved project roots and agents. Use existing repository examples and the current schema; do not guess unsupported keys. A minimal shape is:

agents:
  codex:
    registryId: codex-acp
projects:
  - name: projects
    path: /home/user/projects
defaultAgent: codex
terminal:
  enabled: true
  backend: pty

Replace /home/user/projects with an approved, existing absolute directory. Verify that registry-backed launchers such as npx or uvx, or any configured local commands, are available to the systemd user service. Keep the config mode at 0600.

Only configure voice input if the user approved it. Trit supports batch provider types xai-rest, wispr-flow-rest, and openai, and streaming provider types xai-streaming, wispr-flow-streaming, and openai-realtime. For example:

speechToText:
  defaultProvider: openai
  providers:
    openai:
      type: openai
      apiKeyEnv: OPENAI_API_KEY
      languages: [en]

Use the approved provider and languages rather than copying the example blindly. Have the user enter the API credential directly into ~/.config/trit/env under the configured apiKeyEnv; do not request or display its value. The microphone control appears only after Trit loads that credential. Omit speechToText entirely when voice input is not approved.

For local-only or SSH-forwarded use, retain:

TRIT_AUTH_MODE=local
HOST=127.0.0.1
PORT=9420

For optional remote access, keep the origin on loopback, configure a Cloudflare Tunnel to it, protect the hostname with Cloudflare Access, and set the following values in ~/.config/trit/env:

TRIT_AUTH_MODE=cloudflare-access
TRIT_PUBLIC_ORIGIN=https://trit.example.com
TRIT_CF_ACCESS_TEAM_DOMAIN=your-team.cloudflareaccess.com
TRIT_CF_ACCESS_AUD=your-access-application-audience
TRIT_ALLOWED_EMAILS=owner@example.com,friend@example.com
HOST=127.0.0.1
PORT=9420

Do not expose port 9420 directly. Follow the stable Cloudflare remote-access guide.

Only enable thread sharing if the user approved it. Keep it on a separate loopback listener and public hostname:

TRIT_SHARE_PUBLIC_ORIGIN=https://share.example.com
TRIT_SHARE_HOST=127.0.0.1
TRIT_SHARE_PORT=9520

For email-restricted links, also set TRIT_SHARE_CF_ACCESS_AUD to the audience of a dedicated Cloudflare Access application for share.example.com/e/*. The share listener reuses TRIT_CF_ACCESS_TEAM_DOMAIN to verify Access signatures. Do not reuse the main Trit application audience. Configure the tunnel to route the share hostname to port 9520; never expose that port directly. Follow the thread-sharing guide.

After configuration changes:

chmod 600 "$HOME/.config/trit/config.yaml" "$HOME/.config/trit/env"
systemctl --user daemon-reload
trit restart

7. Verify and report

Run all applicable checks:

trit version
trit paths
trit doctor
systemctl --user is-enabled trit.service
systemctl --user is-active trit.service
curl -fsS http://127.0.0.1:9420/health
journalctl --user-unit trit.service --since '-5 minutes' --no-pager

If voice input was enabled, open a thread in the browser, confirm that the microphone control appears, record a short phrase, and verify that its transcript is inserted into the prompt without being submitted automatically.

If thread sharing was enabled, confirm that http://127.0.0.1:9520/health succeeds, that /api/threads and /ws/thread/example return 404 on port 9520, and that a short-lived test share becomes unavailable immediately after revocation.

Then report:

• Installed Trit version
• Access URL and whether it is local-only, SSH-forwarded, or Cloudflare-protected
• Configured project roots, agents, terminal backend, voice-input status and provider, and thread-sharing status and hostname
• Service and health-check status
• Every path created or changed
• Backup location, if any
• Any skipped or failed check and the exact next action

Do not claim success unless trit doctor, the systemd user service, and /health all succeed. Do not delete backups as part of setup.