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?

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
• 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.

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.

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

Then report:

• Installed Trit version
• Access URL and whether it is local-only, SSH-forwarded, or Cloudflare-protected
• Configured project roots, agents, and terminal backend
• 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.