Skip to main content
Trust boundary: the sandbox is the boundary. The bot and the host are trusted. The mounted project directory and everything inside it are untrusted. Celly favors invariants that are enforced in code and asserted at runtime over documentation that relies on good behavior.

Boundary map

argv-only spawns

Every sbx invocation uses spawn(bin, args, { shell: false }). No command is ever passed through a host shell: sandbox names are validated by regex, and project paths and !cmd are passed as single argv elements. Only src/sbx.ts spawns processes; a unit test guards that against regressions.

Per-project microVM

Each project runs in its own sbx sandbox with only its project directory mounted. The host filesystem outside that directory is unreachable by the agent.

Path containment and denylist

  • A project’s directory must resolve (realpath, case-insensitive) inside PROJECTS_ROOT. Ancestors and descendants of denied paths are rejected too.
  • Text attachments are sanitized (basename only, no .., no reserved Windows device names, no control characters) and written under .celly/inbox with a containment check after resolution.
  • A single helper owns path logic; call sites do not hand-roll it.
The full denylist is in Configuration.

Loopback and password

The generated sandbox config enables password auth (OPENCODE_SERVER_PASSWORD), and the server is published only on loopback. The per-project password is written to ~/.config/celly/opencode.env (mode 0600) inside the sandbox and stored in the bot database. It rotates when a sandbox is recreated.

Admin and backup surfaces

  • The admin page binds 127.0.0.1:ADMIN_PORT only and has no authentication by design: it is safe precisely because it is not network-exposed. The consequence is that anything running locally on the host can read status and redacted log tails and start or stop projects, so local code shares the host trust boundary. It must never be rebound to 0.0.0.0, published, or port-forwarded.
  • It exposes project cards (status, host port, sandbox name, spend, tokens, and session count), start/stop/restart actions, per-project redacted log tails and session details, usage/cost totals, and the audit tail. Log redaction reuses the same redact path as bot.log. The console can also create and remove projects: removal deletes the Discord channel and the sandbox and keeps the host directory. It remains unauthenticated and loopback-only.
  • /dashboard (owner-only) posts the console URL to Discord. The URL is a loopback address, so it only opens on the host or through an SSH tunnel; revealing it does not expose the console to other devices.
  • Backups are written under DATA_DIR/backups (VACUUM INTO output) and stay in the host trust domain, alongside bot.db.
See Operations for how to run and reach these surfaces.

Bot-enforced permission policy

The sandbox config sets a default-deny policy, and the bot verifies it at the API layer after every wake and health check so a project-level opencode.json cannot weaken it. A config PATCH tears down the project’s OpenCode instance and aborts every running thread, so the bot reads the running policy first and only re-writes it when a rule is missing or weakened — the read is what re-asserts the policy after a wake. The policy is built by cellyPolicy() in src/opencode.ts; the full set is below.
  • The bash deny list blocks publishing (npm, pnpm, yarn, including version-suffixed npm@<v> / npx npm@<v> forms), git push, git clean with force plus directories in any flag order, git alias writes (git config … alias.…), env inspection (printenv, env, xargs … printenv, find … -exec printenv), and reads of opencode.env, ~/.config/celly/, or the sandbox’s git credential store (~/.git-credentials) — including via the inspection utilities awk, base64, cat, cp, grep, head, less, od, sed, strings, tail, and xxd, plus catch-all patterns that also cover glob and variable spellings (~/.config/cel?y/opencode.en?), and a host-side check that treats any word which could spell those paths under globs or variables as a match.
  • When a shared GITHUB_TOKEN is configured, git push moves from deny to ask: it goes through the normal approval flow instead of being blocked (runs in auto, asks in buttons, rejected in plan). Everything else stays denied.
  • Celly evaluates every command in a shell line: each ; / && / || / | / & segment, command substitutions ($(...), backticks), find … -exec payloads, here-strings, and heredoc bodies fed to a shell (heredoc bodies that are data for another command are not executed and are not scanned as commands). Commands that cannot be statically analyzed (process substitution, variable executables, eval/source, compound control keywords, unbalanced quotes, substitutions in command position, a shell reading its script from stdin — a bare bash, or … | bash — or home paths built from variables defined elsewhere, e.g. cat ~/$dir/$file) fail closed: they require approval in buttons mode and are rejected in auto and plan mode.
  • external_directory: deny keeps tools inside the mounted project.
  • question: "allow" lets the agent ask questions; Celly decides per approval mode. auto and plan reject them immediately, and buttons surfaces them to authorized members. There is no headless deadlock either way.
  • Any permission request that still surfaces is answered from the policy — there is no catch-all auto-allow.

Approval decisions

buttons mode turns mutating permission requests into Discord messages. Decisions are bound to the pending request id and are only accepted while the request is live; stale or post-restart clicks answer “this request is no longer active”. Read-only tools and every pattern already denied by the policy (bash deny list, sensitive paths, unknown tools) are decided without asking. Every request dropped without a decision (run ended, opencode resolved it, or the timeout fired) is logged with its request id and cause; post-restart drops leave no log line because pending requests are held in memory only. Every permission decision, question answer or rejection, !shell command, /mode change, /task addition or removal, project start/stop/restart/remove, /budget set, and archive-prompt session removal is appended to DATA_DIR/audit.jsonl (mode 0600, one JSON object per line) with timestamp, channel, thread, actor, kind, detail, and decision. The file rotates like the logs (LOG_MAX_BYTES / LOG_MAX_FILES, copies as audit.jsonl.1…), and the admin tail reads only the end of the file. Audit appends are best-effort: a failure logs and never fails the interaction. The log stores tool names, patterns, and shell commands verbatim and never tokens or passwords.

Worktrees

Thread worktrees live under <project>/.celly/worktrees/<slug>, inside the same mounted project directory and the same per-project microVM as the project root. They add no new host paths: the PROJECTS_ROOT containment and sensitivity checks still apply, .celly/ is appended to the project’s .gitignore on first use, and every git invocation runs in the sandbox through argv-only sbx exec. This holds when worktrees are on by default (WORKTREE_DEFAULT=true or /worktree default): the only difference is that a worktree is created when a session is born rather than on demand. If the project is not a git repository — or git worktree add fails — the session silently falls back to the project root and a warning is written to the console; the bot never runs a fallible git operation through a shell. /worktree merge refuses dirty worktrees and dirty project roots before it touches the main branch.

Discord invite permissions

The invite URL the setup wizard prints requests only what the bot needs, by name (the decimal bitfield is built in src/discord-api.ts): It requests only the bot and applications.commands scopes and never more permissions than the table above. The set lives in one place — a permission added there must be added to this table in the same change.

Secrets

  • DISCORD_TOKEN and the optional GITHUB_TOKEN live only in .env (gitignored).
  • Provider credentials live in sbx secret and are injected by the proxy, never stored in the bot or the repository.
  • Managing sbx secret from Discord is deferred; credentials stay host-only.
  • The per-project server password is never placed on a host command line, is never logged, and is masked in /project status.
  • GITHUB_TOKEN, when set, is copied into the sandbox over stdin at bootstrap (mode 0600) into a github.com git credential store. It is deliberately not placed in the sandbox environment — every bash tool child inherits that environment — so git reads the store instead; the deny list still blocks reading the store back out. The token never appears on a host command line and is never stored by Celly itself.
  • Log redaction covers tokens, passwords, and Authorization headers.

Honest caveat

The deny list is defense-in-depth, not a hard isolation boundary. An agent allowed to run bash can still run arbitrary allowed commands. The blast radius is contained by the microVM:
  • OPENCODE_SERVER_PASSWORD only guards a loopback-published port reachable from inside the sandbox and from the host’s 127.0.0.1. The sandbox process environment carries it (the server reads it there), so an agent that dumps the environment can see it; that grants no more than the project’s own local API, and the policy re-assertion repairs any weakening attempt.
  • Provider credentials are injected by the sbx proxy rather than stored in the sandbox.
  • A mounted project is untrusted; never keep secrets in it.
The sandbox is the real boundary. Treat the policy as reducing accidental damage, not as preventing a determined agent from doing anything its allowed commands can do.