.env is the single source of truth. When Celly is started through
npx bot-celly, .env is read from ~/.bot-celly/.env (Windows:
%USERPROFILE%\.bot-celly\.env) instead of the current directory, and
DATA_DIR defaults to ~/.bot-celly/data. Set CELLY_HOME to move that
directory. It is loaded automatically at startup
(process.loadEnvFile), is gitignored, and is validated at boot. A missing or
invalid required value fails fast with an actionable error.
Start from .env.example and set the two required values; everything else has a
working default:
DISCORD_GUILD_IDS accepts a comma-separated list; entries are trimmed, blanks
dropped, and duplicates ignored. DISCORD_GUILD_ID (single guild) is still
accepted when DISCORD_GUILD_IDS is unset.
Variables
DEFAULT_MODEL, DEFAULT_AGENT, APPROVAL_MODE, and WORKTREE_DEFAULT are
seeded into the settings table on the first boot only. Once a value exists
there, it is authoritative and re-reading .env will not overwrite it.GitHub token
GITHUB_TOKEN is optional. When set, Celly copies it into every sandbox — over
stdin, mode 0600, never on a command line — into a github.com git credential
store, so the agent can git clone, fetch, and push private repositories.
It is not exported into the sandbox environment (bash tool children would
inherit it and printenv-class commands could read it back out). GH_TOKEN is
accepted as a fallback. When a token is configured, git push moves from the
hard deny list to the normal approval flow (runs in auto, asks in buttons,
rejected in plan); without one it stays blocked. The token is shared by every
project, is never stored by Celly, and is not readable by the agent (the deny
list blocks ~/.git-credentials).
Easiest way to set it: run bot-celly setup and answer the
“Add a GitHub token…?” prompt. For headless setups pass --github-token, or set
GITHUB_TOKEN in .env directly. Changing the token takes effect the next time
a project starts or wakes: the sandbox policy files are rewritten, and a server
still running with the old policy is restarted automatically.
Multiple guilds
Celly deploys its command set to every guild inDISCORD_GUILD_IDS and runs
boot subscribe and thread reconcile across all of them. At startup each
configured guild is fetched; a guild the bot cannot see (for example, it was
never invited) is skipped with a warning. Startup fails only when no
configured guild is reachable, or when the bot token itself is invalid. A
single guild failing command deployment does not abort startup.
Access control is global:
ACCESS_ROLE_ID, BLOCK_ROLE_ID, and
OWNER_ROLE_ID apply to every configured guild. Role IDs only match in the
guild that owns them, and each guild’s owner (or a member with Manage Guild /
Administrator) is always allowed in that guild. Per-guild role configuration
is not supported. See Limitations.SESSION_BUDGET_USD is the global seed. /budget set <usd> stores
budget_usd:<channelId> in the settings table; that value wins for the
channel, and /budget set 0 disables the budget for it.
PROJECTS_ROOT and path containment
PROJECTS_ROOT is the only directory Celly will mount.
A project directory must resolve (realpath, case-insensitive) inside
PROJECTS_ROOT. On top of containment, a sensitive-path denylist rejects any
project directory that overlaps:
- The bot repository itself (
process.cwd()), unless it containsPROJECTS_ROOT— e.g. the default systemd unit'sWorkingDirectory=%hwith the default~/Celly/projects— in which case it is skipped so the root and its projects remain mountable. DATA_DIR.- Under the user profile:
.ssh,.aws,.gnupg,.config,.docker,.kube,.azure,.npmrc,.netrc,.celly, andAppData. - System directories (
C:\Windows,System32,Program Files,ProgramData, or/etc,/usr,/bin,/sbin,/var,/opt,/System,/Libraryon POSIX).
PROJECTS_ROOT or of any denied path. PROJECTS_ROOT is intentionally not
runtime-editable; changing it means editing .env and restarting.
DATA_DIR
DATA_DIR holds the SQLite database (bot.db), the rotating log
(bot.log), and per-project server logs (logs/<sandbox>.log). The
single-instance lock is a loopback TCP port, not a file. DATA_DIR is
gitignored and created on boot.
Idle auto-stop
WithIDLE_STOP_MINUTES set to a value greater than 0 (default 0,
disabled), Celly stops a project’s sandbox after that many minutes without
message, prompt, or !shell activity. Projects with a run in flight and
projects still provisioning are skipped. Celly posts a plain notice in the
project channel; the next message wakes the project again. Leave
IDLE_STOP_MINUTES=0 to keep every started project running.
Admin page, backups, and logs
ADMIN_PORT, log rotation, SQLite backups, and restore are covered in
Operations, which is the single source for those
surfaces.
Related
- Operations — admin page, logs, backups, restore.
- Security — the invariants behind path containment.
- Providers — registering credentials with
sbx secret.