Boundary map
argv-only spawns
Everysbx 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 ownsbx 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/inboxwith a containment check after resolution. - A single helper owns path logic; call sites do not hand-roll it.
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_PORTonly 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 to0.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
redactpath asbot.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 INTOoutput) and stay in the host trust domain, alongsidebot.db.
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-levelopencode.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.
Full permission policy (JSON)
Full permission policy (JSON)
- The
bashdeny list blocks publishing (npm,pnpm,yarn, including version-suffixednpm@<v>/npx npm@<v>forms),git push,git cleanwith force plus directories in any flag order, git alias writes (git config … alias.…), env inspection (printenv,env,xargs … printenv,find … -exec printenv), and reads ofopencode.env,~/.config/celly/, or the sandbox’s git credential store (~/.git-credentials) — including via the inspection utilitiesawk,base64,cat,cp,grep,head,less,od,sed,strings,tail, andxxd, 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_TOKENis configured,git pushmoves fromdenytoask: it goes through the normal approval flow instead of being blocked (runs inauto, asks inbuttons, rejected inplan). Everything else stays denied. - Celly evaluates every command in a shell line: each
;/&&/||/|/&segment, command substitutions ($(...), backticks),find … -execpayloads, 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 barebash, or… | bash— or home paths built from variables defined elsewhere, e.g.cat ~/$dir/$file) fail closed: they require approval inbuttonsmode and are rejected inautoandplanmode. external_directory: denykeeps tools inside the mounted project.question: "allow"lets the agent ask questions; Celly decides per approval mode.autoandplanreject them immediately, andbuttonssurfaces 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 insrc/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_TOKENand the optionalGITHUB_TOKENlive only in.env(gitignored).- Provider credentials live in
sbx secretand are injected by the proxy, never stored in the bot or the repository. - Managing
sbx secretfrom 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 (mode0600) into agithub.comgit 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_PASSWORDonly guards a loopback-published port reachable from inside the sandbox and from the host’s127.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
sbxproxy rather than stored in the sandbox. - A mounted project is untrusted; never keep secrets in it.
Related
- Architecture — where these controls live.
- Configuration — the path denylist and
DATA_DIR. - Operations — the admin page and backups.
- Limitations — what is not yet enforced.