Sharing a bot
TeleCoder’s original access model is one flat list: everyone in
ALLOWED_USER_IDS can do everything. That is right for a bot with one user, and
it stops being right the moment you add a second — an approval prompt the person
who triggered it can tap themselves is not an approval.
So an instance can split its users into admins and guests. Guests use the agent normally; admins own the parts that reach past their own session.
One owner answering every prompt becomes its own bottleneck, though, so there is a tier in between: an approver is a guest who can answer someone else’s permission prompt. They stay a guest in every other respect — the charter judge still reads their messages, the gate still stops their tool calls, and the lifecycle commands still refuse them — and they cannot approve their own request, which is what keeps the prompt meaningful.
# .env — a bot shared with friends in one groupALLOWED_USER_IDS=111,222,333 # you and two friendsADMIN_USER_IDS=111 # just youAPPROVER_USER_IDS=222 # can unblock a prompt, owns nothingALLOWED_GROUP_IDS=-1001234567890 # the group you shareRESTRICT_TO_GROUPS=true # guests can't take it into a DMWORKSPACE_DIR=/srv/shared # the only projects the picker offersThree layers decide what needs a human, from cheapest to smartest:
| Layer | Catches | Costs |
|---|---|---|
| Permission gate | destructive commands — rm -rf, sudo, force-push, DROP TABLE |
a regex |
| Scope guard | a tool call naming a path outside the projects, or any credential path | a path check |
| Charter judge | what neither of those can see — “open a tunnel to this box”, “email me the projects folder” | a Haiku call, ~5s per guest message |
The first two stop a tool call mid-turn. The third runs before the message reaches Claude, so a held request is still a sentence a person can read rather than a diff to review afterwards.
What that buys you:
- Approval prompts go to admins, and to whoever you name in
APPROVER_USER_IDS. A guarded command pauses, and the prompt names them with a real Telegram mention — so it notifies you even in a muted group, and even if you have no @username. Everyone else tapping it gets told who they’re waiting on; an approver tapping their own request gets told why that one is the exception. Unanswered, it denies afterPERMISSION_PROMPT_TIMEOUT_MINUTES. - A decision can be made once instead of forty times. A job built out of
guarded commands — a dependency bump that runs
rm -rf node_modulesfour times, a rebase that force-pushes twice — costs a tap each, and a guardrail people tap without reading is worse than one that isn’t there. So/autoapprove 30manswers them in advance for one chat. Admins and approvers can open one; it posts every command it waves through, announces itself when it lapses, and a restart closes it.mkfs,dd of=/dev/…,DROP DATABASE,terraform destroyand credential reads still ask, because those are not tedium./autoapprove offends it early,/autoapprove statusreads it back. - The gate turns itself on. With guests present you get prompts without
setting a second variable;
TELECODER_PERMISSION_PROMPTS=0opts out. - Lifecycle and transport are yours.
/update,/restartbot,/rebuildbot,/method,/providerand/ccrrefuse a guest. - The same gate on every transport. It is a PreToolUse hook on the SDK
transport (the default, and the one CCR uses) and on the PTY one, in every
/modeincluding bypass, and it covers subagents’ tool calls too. If it breaks while judging a call, the call is denied. - Out-of-scope paths prompt too.
cat ~/.ssh/id_rsa, an edit to a project nobody was invited to, a read of this bot’s own.env— all held. System paths and language toolchains stay readable without prompting, because a guardrail that fires oncat /etc/os-releaseis one people learn to tap through. - A charter in plain language. Drop a
CHARTER.mdin your workspace root (or pointCHARTER_FILEat one) and every guest message is read against it first. No charter, no problem — a default is generated from the allowed roots. The judge only ever asks; it never refuses on its own, and it fails open, with the scope guard underneath as the deterministic backstop. /permissionsreports the truth. Gate state, scope roots, which charter is in force, your role, and the guarded patterns.- Letting someone in takes one tap. A stranger who posts in the shared group
gets a refusal and an approve card naming them, mentioning the admins so it
notifies you in a muted group. Tap Allow and they’re a guest immediately — no
.envedit, no restart. Someone added to the group is asked about the moment they join, before they’ve said anything.
Write the house rules in CHARTER.md at your workspace root — see
CHARTER.example.md for a starting point.
Admitting people from chat
Section titled “Admitting people from chat”ALLOWED_USER_IDS is read once at startup, so every new person there costs an
edit and a restart. /allow is the runtime half of the same list:
| Command | What it does |
|---|---|
/users |
Who can use this bot: admins, .env guests, guests admitted from chat, and people seen in the group but not let in |
/allow |
Admit someone as a guest — reply to their message, or /allow @user / /allow 12345 |
/deny |
Remove someone /allow admitted |
All three are admin-only, and take effect immediately. With several bots, each
keeps its own list: /allow lets someone into the bot you sent it to and no other,
and /deny takes them out of that one.
Reply to their message rather than typing a handle. Telegram gives bots no
way to resolve a @username — there is no such API call, getChatAdministrators
covers only a group’s admins, and nothing enumerates ordinary members. So the
only handles this bot can match are the ones it has watched go by, and a reply
is both exact and the one form that works for the many people who have no
username at all. A handle it hasn’t seen gets told so, rather than failing
mysteriously.
Ids are the identity throughout. A Telegram username can be dropped and claimed by someone else, so it’s re-resolved on every use and never stored as the thing being allowed.
Admitting someone makes them a guest, which switches on the permission gate, the
scope guard and the charter judge if they weren’t already on. /deny on an id
that came from ALLOWED_USER_IDS reports where it actually lives instead of
appearing to work until the next restart.
[!IMPORTANT] All of the above is supervision, not isolation. Claude still runs as your Unix user, so a guest’s session can reach anything that user can — auto mode asks before the riskier steps, but it is Claude’s judgement, not a boundary.
WORKSPACE_DIRscopes the project picker, not the filesystem. For a real boundary, run the shared instance as its own Unix account.
Group roles
Section titled “Group roles”Access in a group has three tiers. Admins (ADMIN_USER_IDS, or everyone in
ALLOWED_USER_IDS when that is unset) have full access everywhere and are the
only ones who can hand out the rest. Contributors can prompt the agent in
that group. Spectators are in the chat and ignored by the bot — they read
along and talk to everyone, and the bot only answers them with a (rate-limited)
note if they address it directly, alongside a card an admin can tap to let them
in.
This layers on the bot’s roster rather than replacing it: anyone in
ALLOWED_USER_IDS, or admitted with /allow in a DM, is a contributor in every
group without a per-group grant. /users reads back that bot-wide list;
/members reads back one group.
GROUP_MEMBERS_DEFAULT picks which of the last two an ungranted member lands
in. spectator is the default: nobody can prompt the agent until an admin runs
/allow, so adding someone to the chat is not the same as handing them a shell.
contributor makes Telegram membership the whole gate — right for a group of
peers who all own the box.
Commands that reconfigure the bot rather than drive the conversation stay with
admins — /restartbot, /rebuildbot, /update, /mode, /method,
/provider, /ccr, /permissions, /teleport, /project, /newproject,
/newbot, /users, /allow and /deny, along with the inline buttons those
open. A contributor drives the conversation; only an admin repoints or restarts
the bot. /members is readable by anyone who can prompt.
A real boundary: its own Unix account
Section titled “A real boundary: its own Unix account”Supervision decides what needs your attention. Unix decides what is reachable at all. If the people you’re sharing with shouldn’t be able to read your other projects even in principle, the shared bot needs an account that owns nothing but the shared projects:
sudo ./scripts/setup-shared-bot-user.sh --operator "$USER"That script locks down your home directory, creates a telefriends account with
no sudo and no docker (the docker group is root-equivalent), gives it a projects
directory and its own TeleCoder checkout, writes a starter .env with the
sharing settings already filled in, and installs a lingering systemd --user
service so it survives a reboot. Authenticating Claude and pasting the bot token
stay yours — both are interactive, and neither belongs in a script’s arguments.
It ends by verifying its own work, which you can re-run at any time:
sudo ./scripts/setup-shared-bot-user.sh --verifyThe check doesn’t reason about modes; it becomes the account and tries to read your secrets, which is the only form of that answer worth trusting.
[!WARNING] Check this before adding any account: a home directory at mode
0751lets other accounts traverse into it, so every world-readable file inside is reachable by absolute path — and a.envwritten at the default0664is one of them.--verifyreports it; the setup script fixes it.