125 lines
17 KiB
Markdown
125 lines
17 KiB
Markdown
# User guide
|
|
|
|
How to use slackerbot from Slack.
|
|
|
|
## Your container
|
|
|
|
| Where you talk to the bot | Container | Who can use it |
|
|
| ------------------------------------------------------- | ---------------- | ---------------------- |
|
|
| DM with the bot | `u-<user id>` | Only you |
|
|
| Channel, private channel or group DM (@mention the bot) | `c-<channel id>` | Anyone in that channel |
|
|
|
|
In channels, @mention the bot to start a session. In a session's thread, the bot by default only reads replies that @mention it, but a thread can be switched to read every reply (see **Listening in threads** below). Each message reaches the agent with the sender's name in front (e.g. `Alice: try the other branch`), so the agent knows who's asking, and the first message of a session tells the agent which channel it's in.
|
|
|
|
In DMs the bot reads every message. You can also chat with it in Slack's assistant pane (the bot's icon in the top bar). Each chat there is its own session, its first message can be a command (the suggested **Container status**, **Past sessions** and **What can you do?** buttons send `status`, `sessions` and `help`), and the agent is told which channel you have open next to it.
|
|
|
|
## Talking to the agent
|
|
|
|
1. Send a message. If the container is stopped, the bot starts it, and if it doesn't exist yet, the bot creates it. Your home folder (`/root`) is kept between starts. The container comes with few tools, but it has Nix with flakes, and the agent is told to give each project a `flake.nix` with a dev shell rather than installing things globally. Anything outside `/root` is gone after a restart.
|
|
2. A new top-level message starts a **new session**, and the reply goes in a thread.
|
|
3. **Reply in that thread to continue the same session**, even days later. `sessions` lists past ones.
|
|
4. The answer streams in as the agent works. Tool calls show up as 🔧 lines. Your message gets 👀 while the agent works, then ✅ when it's done or ⚠️ if something went wrong.
|
|
5. While the agent works, its reply shows what it's doing (thinking, running a tool, writing the reply), when the agent last sent anything, and a **Cancel** button. They go away when the reply is done. To stop a reply part-way, press **Cancel**, or react to your message or the bot's reply with ❌ (`:x:`) or 🛑 (`:octagonal_sign:`). The reply ends with _(cancelled)_, and the session carries on with your next message. `running` lists every reply in progress in the channel, and `cancel all` cancels them all at once.
|
|
6. Messages in one thread run one at a time. If two people post at once, the second waits its turn.
|
|
7. Containers unused for longer than their idle limit are stopped (default 6 hours, see `keep`). Files are kept, and the bot posts to say it stopped the container.
|
|
8. **Container updates have their own thread.** Each time a container starts, the bot posts a top-level "Starting container" message in the channel (or your DM) and pins it. Every step goes in that message's thread as its own reply, saying what the bot is waiting for: placing it on a node, creating the home folder and launching it, and waiting for the agent. A last reply says the container is up. Your own thread only gets one message with a link to it. Stopping a container (`stop`, the **Stop** button or the idle limit) is reported in the same thread, ending with a reply that it's down. The pin is replaced the next time the container starts.
|
|
|
|
9. **Attach files** to your message (images, logs, zips) and they're copied into the container at `/root/slack-uploads/<message time>/<name>`, and the agent is told where. A message with files always goes to the agent, never to a command. Files over the server's size limit (default 100 MB) are left out, and the home folder's max size still applies.
|
|
10. **The agent can send you files.** It has a `send_file` tool, and the files land in the thread when its reply ends, where Slack previews images, video and PDFs. At most 5 files per reply, each under the server's size limit.
|
|
11. **The agent can run the commands below for you**, so you can ask it things like "give yourself 8G" or "keep running over the weekend". It runs them as you, the sender of the message it's answering, with your permissions. Anything that changes the container is posted in the thread as ":robot_face: The agent ran `scale 8G` for Alice", with the bot's answer. If the agent stops the container, it waits until the reply ends. Its moves get their own thread like any other move. It can do everything a command can except `help`, and it can't press buttons. When it runs `cancel all`, its own reply carries on.
|
|
12. **Restarts don't lose your reply.** If slackerbot restarts while the agent is working on your message, the reply ends with a note that it's restarting. When it's back, it posts ":arrows_counterclockwise: slackerbot restarted part-way through this reply, so I'm picking it back up" in the thread, and the agent carries on where it stopped (or starts, if it hadn't got your message yet). After an hour, or after 3 restarts in a row, it asks you to send the message again instead. Messages sent while slackerbot is down aren't seen, so send those again.
|
|
13. **System updates ask first.** When the server gets a new container system (new tools, for example) while yours is running, the bot asks once, under the agent's next reply, whether to restart onto it. **Restart now** restarts the container right away (it waits if the agent is still replying), and **Later** leaves it alone. Either way, `/root` and your sessions are kept, and the update also applies the next time the container starts for any reason.
|
|
|
|
Other replies you may get:
|
|
|
|
- **"maxed out":** no node has room right now. Try again later.
|
|
- **"being moved, try again in a moment":** a move is in progress.
|
|
- **"dead slave":** the node your container lives on is offline. Pick **Create new container** to get a fresh one on a healthy node (old sessions won't carry over), or **Wait** to get a message when the node is back.
|
|
|
|
## Listening in threads
|
|
|
|
Channel threads start out in `only-mentions`: the bot only reads replies that @mention it. Switch with `@slacker /listen …` (the mention matters, because Slack treats a message starting with `/` as a slash command). `listen` without the slash works too.
|
|
|
|
| Command | Where | What it does |
|
|
| ---------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------- |
|
|
| `@slacker /listen all-messages` | in a session's thread | The bot reads every reply in this thread |
|
|
| `@slacker /listen only-mentions` | in a session's thread | Back to replies that @mention the bot |
|
|
| `@slacker /listen` | in a thread | Shows what this thread does |
|
|
| `@slacker /listen channel all-messages` (or a top-level `@slacker /listen all-messages`) | anywhere in the channel | Sets the channel's default for threads that haven't set their own |
|
|
| `@slacker /listen channel` | anywhere in the channel | Shows the channel's default |
|
|
|
|
Anyone in the channel can change these. In an `all-messages` thread, `move` still needs an @mention, so a chatty "move on" doesn't move the container. DMs always read every message.
|
|
|
|
## Commands
|
|
|
|
Send these as a **new message**, not in a thread. `move` and `listen` are the exceptions, and also work in a thread. In the assistant pane, the first message of a chat counts as new.
|
|
|
|
| Command | What it does |
|
|
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `help` | Shows the command list |
|
|
| `status` | State, size, time unused and idle limit, with **Stop** and **Scale up** buttons |
|
|
| `sessions` | Past sessions with links. Open one and reply in its thread to continue |
|
|
| `running` | Replies the agent is working on in this channel right now, with links, who asked and how long ago they started |
|
|
| `cancel all` | Cancels every reply in progress in this channel, like pressing **Cancel** on each. Sessions are kept. Replies still starting the container are left |
|
|
| `stop` | Shuts the container down. Files are kept |
|
|
| `scale up` / `scale down` | Doubles or halves RAM and CPU |
|
|
| `scale 8G 4cpu` | Sets an exact size |
|
|
| `scale +2G` / `scale -1cpu` / `scale 512M +0.5cpu` | `+` or `-` changes by that much. Memory and CPU can be mixed or left out |
|
|
| `keep 24h` (or `3d`, `1d12h`, `2w`, `5 hours`) | Stops the container after that long unused |
|
|
| `keep indefinite` (or `forever`) | Never stops it for being unused. Use `stop` when done |
|
|
| `keep default` | Back to the server's default |
|
|
| `keep` | Shows the current idle limit |
|
|
| `storage` | Shows home folder usage, guaranteed space and max |
|
|
| `storage 20G` / `storage +5G` / `storage -2G` | Sets or changes the max (the cap) |
|
|
| `storage min 8G` / `storage min 8G max 20G` | Sets the guaranteed space, or both |
|
|
| `nodes` | Every node with what's free on it, and where this container runs. Flags nodes running a different version than the master |
|
|
| `move <node>` / `move to <node>` / `migrate <node>` | Moves this container to that node |
|
|
| `move` / `move auto` | Moves it to whichever other node keeps resources most even |
|
|
| `permissions` | Who may change what here |
|
|
| `in-flight` / `in-flight all` | Super users only. For debugging: shows the replies slackerbot would pick back up after a restart, here or in every channel. Only you see the answer |
|
|
|
|
If what follows `scale`, `keep`, `storage` or `move` doesn't look like a size, a time or a node (e.g. "keep the tests passing"), the message goes to the agent instead.
|
|
|
|
**Scale:** memory takes `G`/`GB` or `M`/`MB`, and CPU takes `cpu`/`cores` (fractions are fine). The minimum is 256 MB and 0.25 CPU, and the server sets a maximum. A running container changes size right away, and a stopped one gets the new size when it next starts. Shrinking memory below what's in use may stop programs inside.
|
|
|
|
**Keep:** the minimum is 10 minutes. The server can cap the maximum or turn off `keep indefinite`. Setting `keep` restarts the countdown.
|
|
|
|
**Storage:** sizes take `M`, `G` or `T`. Both numbers are at least 512 MB, the guarantee can't be more than the max, and the max can't go below what's already used. If the drive can't promise a bigger guarantee, the bot refuses it. You can raise the max even when the caps on that drive already add up to more than it holds. The bot flags the drive as **overbooked** but still makes the change.
|
|
|
|
**Moves:** each move gets its own top-level message saying who started it, with progress in its thread and ✅ or ❌ when done. A running container keeps running during the bulk copy, and is only stopped briefly for a final sync. Sessions come along. When a container's node is too full to restart it, the bot moves it automatically.
|
|
|
|
## Permissions
|
|
|
|
Anyone can talk to the agent and use `status`, `sessions`, `running`, `cancel all`, `nodes`, `permissions` and `stop`, and can view settings with a bare `keep` or `storage`.
|
|
|
|
**Changing** a container needs a permission:
|
|
|
|
| Permission | Covers |
|
|
| ---------- | ------------------------------------------------ |
|
|
| `scale` | `scale …` and the **Scale up** button |
|
|
| `storage` | `storage <size>`, `storage min …` |
|
|
| `move` | `move …` and **Create new container** |
|
|
| `keep` | `keep <time>`, `keep indefinite`, `keep default` |
|
|
| `all` | The four above |
|
|
| `manage` | Editing this channel's permission list |
|
|
|
|
Roughly how it fits together:
|
|
|
|
- **Channels** use a server-wide **default list** of super users, unless the channel has its **own list**. Your first `grant` in a channel copies the default list into it, so nobody loses access.
|
|
- **DMs** have no list. Instead, a server-wide switch per permission says whether people may change their own DM container (on unless turned off).
|
|
- **User managers** can change everything: any channel's list, the default list, DM switches and the manager list. **Channel managers** (`manage`) can only edit their own channel's list. There's always at least one user manager.
|
|
- If you lack a permission, the bot answers with :lock: and names who has it, without tagging them.
|
|
- Automatic moves don't need a permission.
|
|
- `in-flight` shows other people's messages, so it needs you to be a **super user** (anyone on the list that applies here, with any permission) or a user manager. `in-flight all` needs you on the default list, or a user manager. DMs count the default list.
|
|
|
|
| Command | Who | What it does |
|
|
| ------------------------------------------------------------- | ---------------------- | ---------------------------------------------------- |
|
|
| `grant @alice @bob move scale` | channel managers | Grants permissions in this channel |
|
|
| `revoke @alice move` / `revoke @alice` | channel managers | Removes some or all of someone's permissions here |
|
|
| `permissions reset` | channel managers | This channel goes back to the default list |
|
|
| `grant default @alice all` / `revoke default @alice` | user managers | Changes the default list |
|
|
| `dm storage on` / `dm storage off` | user managers | Changes what people may do on their own DM container |
|
|
| `managers` / `managers add @alice` / `managers remove @alice` | anyone / user managers | Shows or changes the user managers |
|
|
|
|
People named in a `grant`, `revoke` or `managers` change are tagged in the bot's confirmation, so Slack notifies them.
|