Skip to main content
Installing and running Celly is a host action, not a Discord command. See the CLI reference for npx bot-celly, setup, and doctor.
Celly registers guild-scoped slash commands (instant updates) plus a ! shell prefix. /project uses subcommands.

Project management

Owner-only means the guild owner or a member with OWNER_ROLE_ID. The other commands accept the guild owner, Administrator / Manage Server, or the ACCESS_ROLE_ID; BLOCK_ROLE_ID is checked first. list and status are available to any authorized member.

Sessions

Scheduled tasks

Approvals and questions

Approval mode is per project channel. /mode writes the override; the APPROVAL_MODE environment value seeds the global default on first boot.
  • auto — the bot answers every permission request from the enforced policy immediately, exactly like previous releases.
  • plan — a dry run. Read-only tools (read, glob, grep, list, find) run; bash, edit, write, patch, external_directory, webfetch, unknown tools, and sensitive-path reads are rejected.
  • buttons — read-only tools run; every other non-denied request posts an Approve once / Always allow / Reject message in the thread. Requests time out after 5 minutes and are rejected. Deny-listed commands, sensitive paths, and unknown tools are rejected without asking.
With a shared GITHUB_TOKEN configured (see GitHub token), git push is no longer deny-listed; it follows the mode above — runs in auto, asks in buttons, and is rejected in plan. In buttons mode an agent question renders inline in the streamed reply, in the order it was asked, so it does not split the surrounding answer. Its interactive controls live on that message: buttons (one to five options), a string select (six to twenty-five options), a Custom answer button that opens a modal, and a Reject button; they are removed once the request is answered, rejected, or times out. Multi-question requests collect answers in order. Questions time out after 5 minutes and are rejected. auto and plan modes reject questions rather than interrupting the run. Clicking a button from a previous bot process answers “this request is no longer active”; pending requests are not persisted across restarts.

Archived threads

When a managed thread is archived — from Discord’s UI or by Discord’s automatic inactivity timer — Celly posts a notice in the parent project channel, replying to the message that started the thread when there was one. The notice offers:
  • Remove session — delete the OpenCode session (reclaiming sandbox disk) and the thread’s stored record. Its usage is folded into the channel totals first, so /cost history survives. The archived Discord thread is kept as a transcript.
  • Keep — dismiss the notice and change nothing.
Any authorized member can answer, and a run in progress is never prompted. The notice is posted at most once per thread. After a removal, messages posted in that thread are ignored and /resume no longer lists the session.

Worktrees and forks

New sessions can start in a per-session git worktree instead of the project root. This is off by default; enable it globally with WORKTREE_DEFAULT=true or per project with /worktree default state:on. The global value is seeded into settings.worktree_default on first boot, and /worktree default writes a per-project worktree_default:<channelId> override (inherit clears it and falls back to the global value). When a new session opts in, Celly runs git worktree add -b celly/<slug> .celly/worktrees/<slug> HEAD before the OpenCode session is created and points the session at that directory. Non-git projects, an unresolved sandbox path, or a failed git worktree add fall back to the project root and log a warning to the console — session creation never fails because of the worktree. Sessions resumed with /resume keep their existing directory, and /fork copies the source worktree unless new_worktree is set.

Cost and providers

Register provider credentials with sbx secret on the host. Alternately, a provider’s own login flow (for example opencode auth login) can be run inside the sandbox over the terminal opened by /attach. The model and agent lists behind the /model and /agent pickers are warmed at startup and refreshed every 60 seconds, so the pickers open from cache rather than fetching on demand.

Messages and shell

Text-like attachments on a message are size-capped, written to a validated .celly/inbox, and referenced in the prompt. Shell output is chunked across up to three messages; when the output is longer, a fourth notice reports the total length and exit code.
!<command> runs with the same privilege as the agent inside the microVM. It cannot run host commands, but it can do anything the sandbox allows. Treat it as running code.

Admin console

The link only opens on the Celly host itself: the console binds 127.0.0.1 and is never network-exposed. See Operations.

Deferred

Deferred features are tracked on the roadmap. The OpenCode web UI is intentionally not published (the sandbox server stays loopback-only); attach from a terminal instead — see the terminal attach guide. See the architecture reference for what happens under the hood when you run these.