| 1 | # Running T3 Code in the background |
| 2 | |
| 3 | On Linux and macOS, T3 Code can run as a service for your user so you do not need |
| 4 | to keep a terminal open. |
| 5 | |
| 6 | ## Manage the service |
| 7 | |
| 8 | Install the `t3` CLI first ([Install T3 Code](./install.md#command-line)), then |
| 9 | run these commands on the machine that will host T3 Code: |
| 10 | |
| 11 | | Task | Command | |
| 12 | | ------------------------------- | ---------------------- | |
| 13 | | Install and start | `t3 service install` | |
| 14 | | Inspect status and log location | `t3 service status` | |
| 15 | | Move to a newer release | `t3 update` | |
| 16 | | Restart | `t3 service restart` | |
| 17 | | Stop and remove from startup | `t3 service uninstall` | |
| 18 | |
| 19 | Uninstalling the service leaves your projects, threads, and settings intact. |
| 20 | Running `t3 service install` again repairs a service that `t3 service status` |
| 21 | reports as broken. |
| 22 | |
| 23 | `t3 update` downloads the newest release on your channel and switches `t3` |
| 24 | and the service to it. Restarting interrupts running agent turns, terminals, |
| 25 | and remote clients, so it asks first; answer no and the service keeps running |
| 26 | the old version until you run `t3 service restart`. Pass `--yes` from a |
| 27 | script. A server you started by hand is left running; stop and start it again |
| 28 | to pick up the new version. Wait for any remote update already in progress |
| 29 | before updating; to match a remote client's version, follow |
| 30 | [Updating T3 Code](./updating.md). |
| 31 | |
| 32 | Pass an exact version (`t3 update 0.0.42`) to pin one, `--channel nightly` to |
| 33 | switch trains, or `--allow-downgrade` to move backwards. `preview` is a |
| 34 | maintainers' test train: its builds can be broken and are never offered as |
| 35 | updates, so the installer and `t3 update` ask for confirmation before |
| 36 | installing one. |
| 37 | |
| 38 | `t3 uninstall` removes the background service, the `t3` launcher, and the |
| 39 | downloaded versions after showing you the list and asking once. Your projects, |
| 40 | threads, and settings under `~/.t3/userdata` are kept. Pass `--yes` from a |
| 41 | script. |
| 42 | |
| 43 | ## Platform support |
| 44 | |
| 45 | Linux needs systemd user services. Setup enables lingering so T3 Code starts at |
| 46 | boot and keeps running after logout. If this needs administrator permission, |
| 47 | setup prints a recovery command before changing the service. |
| 48 | |
| 49 | macOS starts the service when you log in and stops it when you log out. Keep the |
| 50 | Mac logged in and awake for unattended remote access. Installing over SSH while |
| 51 | nobody is logged in at the Mac's screen can fail at the final start step; the |
| 52 | service is still installed and will start at the next login. |
| 53 | |
| 54 | Windows background services are not supported. |
| 55 | |
| 56 | T3 Connect can offer service installation during setup, but the two are managed |
| 57 | separately. Signing out of T3 Connect does not stop or uninstall the service. |
| 58 | |
| 59 | ## Troubleshooting |
| 60 | |
| 61 | Start with `t3 service status` on the host. It prints the log path and, on Linux, |
| 62 | checks whether the installed service is running, enabled, and allowed to survive |
| 63 | logout. |
| 64 | |
| 65 | If it stops when your SSH session closes, check for `linger-disabled`. An |
| 66 | administrator can enable lingering with: |
| 67 | |
| 68 | ```sh |
| 69 | sudo loginctl enable-linger "$(id -un)" |
| 70 | ``` |
| 71 | |
| 72 | Over SSH, allow sudo to prompt: |
| 73 | |
| 74 | ```sh |
| 75 | ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"' |
| 76 | ``` |
| 77 | |
| 78 | Then retry service setup as your normal user. Run only the `loginctl` command |
| 79 | with sudo; running T3 Code as root creates a separate installation and Connect |
| 80 | identity. Without administrator access, run `t3 serve` in a terminal and keep |
| 81 | that session open. |
| 82 | |
| 83 | | Status problem | Next step | |
| 84 | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | |
| 85 | | `linger-unavailable` | Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available. | |
| 86 | | `user-manager-unavailable` | Run `systemctl --user status` in a login session for the service user; check your distribution's systemd user-session support. | |
| 87 | | `service-disabled` or `service-stopped` | Read the log and `systemctl --user status t3code.service`, then use the repair command printed by T3 Code. | |
| 88 | | `restart-pending` | A newer version is installed but the service still runs the previous one. Run `t3 service restart`. | |
| 89 | |
| 90 | On macOS, check **System Settings → General → Login Items** if the service no |
| 91 | longer starts at login. If agent work cannot access Desktop, Documents, or |
| 92 | Downloads, it may need Full Disk Access for the `t3` executable listed in |
| 93 | `ProgramArguments` in |
| 94 | `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. |
| 95 | |
| 96 | For failures after signing in to T3 Connect, see |
| 97 | [connection troubleshooting](./remote-access.md#t3-connect-troubleshooting). |