Skip to main content
.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 in DISCORD_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 contains PROJECTS_ROOT — e.g. the default systemd unit's WorkingDirectory=%h with 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, and AppData.
  • System directories (C:\Windows, System32, Program Files, ProgramData, or /etc, /usr, /bin, /sbin, /var, /opt, /System, /Library on POSIX).
Because containment is checked both ways, you also cannot register a parent of PROJECTS_ROOT or of any denied path. PROJECTS_ROOT is intentionally not runtime-editable; changing it means editing .env and restarting.
Keep secrets out of project directories. A mounted project is treated as untrusted content, and the agent can read anything inside it (git remotes, .env files, tokens). Use the sandbox credential proxy instead of committing credentials.

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.
Keep DATA_DIR outside OneDrive/Dropbox-style synced folders. Cloud-sync detection is not implemented, so this is on you.

Idle auto-stop

With IDLE_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.
  • Operations — admin page, logs, backups, restore.
  • Security — the invariants behind path containment.
  • Providers — registering credentials with sbx secret.