# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

| Path | Purpose |
| --- | --- |
| `~/.local/share/trit/versions/<version>` | Immutable application release |
| `~/.local/share/trit/current` | Atomic current-release symlink |
| `~/.local/share/trit/trit.db` | SQLite data |
| `~/.config/trit/config.yaml` | Agent and project configuration |
| `~/.config/trit/env` | Mode-`0600` service environment |
| `~/.config/systemd/user/trit.service` | User service |
| `~/.local/bin/trit` | Stable launcher |

## 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:

```yaml
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:

```bash
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`:

```bash
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](https://trit.wtf/remote-access/cloudflare.md).

After configuration changes:

```bash
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:

```bash
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.