# Remotes - [Introduction](#introduction) - [Adding a Remote](#adding-a-remote) - [Creating a Token](#creating-a-token) - [Saving the Remote](#saving-the-remote) - [Listing Remotes](#listing-remotes) - [Switching Remotes](#switching-remotes) - [Working With Several Teams](#working-with-several-teams) - [Renewing a Token](#renewing-a-token) - [Removing a Remote](#removing-a-remote) - [How Remotes Are Stored](#how-remotes-are-stored) - [Troubleshooting](#troubleshooting) ## Introduction A remote is a NiceTryBot control panel that the [`nicetrybot` command](https://docs.nicetrybot.com/docs/0.x/cli.md) on your laptop works with. Once you've added one, the control panel commands, such as `nicetrybot domains add`, run there instead of on the machine you're typing on. Remotes work a lot like Git's: you may save as many as you like, such as one for production and one for staging, give each a short name, and switch between them. The command talks to each remote's [MCP server](https://docs.nicetrybot.com/docs/0.x/mcp.md) over HTTPS, using an API token you create in that control panel. ## Adding a Remote ### Creating a Token Every remote needs an API token. In the control panel, an administrator opens **Admin → API tokens** and creates one:
- Give it a name you'll recognize later, such as `Laptop`. - Choose the team the command should work on, or **All my teams**, so one token works on every team you're on. See [Working With Several Teams](#working-with-several-teams). - Tick only the [abilities](https://docs.nicetrybot.com/docs/0.x/mcp.md#api-tokens) you need. Every token may read; adding and removing domains needs **Add and change domains**. - Choose how long it lasts, from one hour to 90 days.
The token is shown once. The page also shows the exact `nicetrybot remote add` command for your control panel, ready to copy. ### Saving the Remote Pass your control panel's address to `remote add`. When you leave the scheme out, `https://` is assumed: ```shell nicetrybot remote add panel.example.com ``` The command asks for the token without showing it as you paste, checks it with the control panel, saves the remote, and makes it your current one: ```text Make a token at https://panel.example.com/admin/tokens (pick its abilities and how long it lasts). API token: ✓ Saved panel.example.com (https://panel.example.com), team Acme, expires in 30 days. It's the current remote. ``` By default, a remote is named after its host. To give it a shorter name, put the name first: ```shell nicetrybot remote add prod panel.example.com nicetrybot remote add staging staging-panel.example.com ``` > [!NOTE] > You may pass the token with `--token=ntb_…` instead, such as in a script, but letting the command ask for it keeps the token out of your shell's history. ## Listing Remotes To list your saved remotes: ```shell nicetrybot remote list ``` ```text NAME URL TEAM TOKEN * prod https://panel.example.com Acme expires in 29 days staging https://staging-panel.example.com Acme expired: nicetrybot remote auth ``` The `*` marks the current remote. To see just the current one, run `nicetrybot remote` on its own. ## Switching Remotes To make another remote the current one: ```shell nicetrybot remote use staging ``` Running `nicetrybot remote` with a remote's name, or a control panel's address, does the same thing. If no saved remote has that address, the command adds one: ```shell nicetrybot remote prod nicetrybot remote staging-panel.example.com ``` To run a single command somewhere else without switching, use `--remote`: ```shell nicetrybot domains --remote=staging ``` If you run the command on a NiceTryBot server that also has a current remote, `--local` runs a command on the server's own stack instead. To stop using remotes on that machine altogether, run: ```shell nicetrybot remote use --local ``` The full order in which the command decides where to run is described in [Where Commands Run](https://docs.nicetrybot.com/docs/0.x/cli.md#where-commands-run). ## Working With Several Teams A token made for **All my teams** works on every team you're on, so one remote can look after all of them. When you add the remote, the command lists your teams and asks you to pick one: ```text ✓ Saved prod (https://panel.example.com), no team picked yet (token for all teams), expires in 30 days. It's the current remote. Its token works on all your teams (acme, globex). Pick the one to work on: nicetrybot team use SLUG ``` To list the teams, with a `*` beside the one in use, and to switch: ```shell nicetrybot teams nicetrybot team use globex ``` ```text SLUG TEAM * acme Acme globex Globex ``` The remote remembers the team, including when you renew its token. Run `nicetrybot team` to see which team you're on. To run a single command on another team without switching, pass `--team`: ```shell nicetrybot domains --team=acme ``` On every team, the token can only do what you can do there. A token with **Add and change domains** can't add domains to a team where you're a plain member. Teams you join later are included straight away, and teams you leave are gone straight away. A token for one team keeps working on that team only. Naming another team gives an error that says which team the token is for. ## Renewing a Token API tokens always expire. When a remote's token has expired, create a new one in **Admin → API tokens** and give it to the remote. A token for all teams stays on the team you picked: ```shell nicetrybot remote auth prod ``` Leave the name out to renew the current remote's token. ## Removing a Remote To forget a remote: ```shell nicetrybot remote remove staging ``` This only removes the remote from your laptop. Its token keeps working until it expires, so if you're done with it, delete it in **Admin → API tokens** as well. ## How Remotes Are Stored Each remote is a small file in `~/.config/nicetrybot/remotes`, holding the control panel's address, its token, its team (and whether the token works on all of them), and when the token expires. The directory and its files are readable only by you. If you set `XDG_CONFIG_HOME`, they live under that instead, and `NICETRYBOT_CONFIG_DIR` may point the command somewhere else entirely. The token is sent only to the remote's own `/mcp` path, in an `Authorization` header. The command hands it to `curl` on standard input rather than on the command line, so other users on your machine can't see it in the process list. > [!WARNING] > Treat your remotes directory like a password manager's file. Anyone who can read it may act as you on the tokens' teams until they expire. Prefer short-lived tokens with only the abilities you use. ## Troubleshooting **The command says the remote "doesn't take that token".** The token has expired or been deleted, its user is no longer an administrator or no longer on the team, or there's no NiceTryBot control panel at that address. Without a working token, the MCP server answers exactly as if it didn't exist, so the command can't tell which. Create a new token and run `nicetrybot remote auth`. **The command says the remote "has no" tool.** The control panel runs an older release that doesn't have that tool yet, or your token isn't allowed to use it. `nicetrybot tools` lists what your token may use. Update the control panel with `nicetrybot update`, or create a token with the ability you need. **The command asks for `jq`.** Install it with `brew install jq` on macOS, or `apt-get install jq` on Linux.