boxcode

Docs

From install to a working session.

Boxcode is a coding agent for the terminal and the editor. This page is the user guide: install, sign in, features, CLI, IDE, and config.

Quick startSign in path

01

Quick start

  1. 1. Install the CLI

    Checksum-verified binary — no Rust toolchain. The IDE chat participant expects this on your PATH, so install the CLI even if you only want the editor.

    curl -fsSL https://boxcode.sh/install.sh | bash

    Already installed? boxcode --upgrade

  2. 2. Sign in

    Promo credits live on llm.boxcode.sh. From a terminal:

    boxcode login

    The browser opens Google if you are not already signed in on boxcode.sh, then an Authorize page. Click Authorize — no codes to copy. Credentials are written to ~/.boxcode/config.toml. The IDE reads that same file.

  3. 3. Run it in a project

    cd your-project
boxcode

    Type a sentence and press Enter. Alt or Shift-Enter for a newline. Destructive actions wait for y/n. /plan researches first if you want an approve-able approach before any writes.

  4. 4. Optional — IDE

    Download Boxcode IDE after the CLI is on PATH. Open a folder and send a message in chat. Sign in from the IDE if you skipped boxcode login.

    Download IDE

02

Sign in path

Login is Google-only. It links this machine to your boxcode.sh account and mints a promo key on llm.boxcode.sh. You do not need it if you already have your own API key — use /provider instead.

  1. 01

    Start from CLI or IDE

    boxcode login, /login inside the TUI, or Sign in in the IDE. The app opens the browser.

  2. 02

    Google on boxcode.sh

    If this browser is not signed in, you go through Google. The site Sign in button does the same.

  3. 03

    Authorize

    The device page asks Boxcode to connect to your account. Click Authorize. The code never shows as a Device ID.

  4. 04

    Config is written

    ~/.boxcode/config.toml gets endpoint, model, and key. ~/.boxcode/account.token is the device session. Both CLI and IDE use this.

CLI

boxcode login
boxcode logout

Same commands as /login and /logout in an open session.

Website

Sign in goes straight to Google. After that, /account shows spend, remaining promo credit, and the key prefix.

Override the site URL for the device flow with BOXCODE_AUTH_URL=https://boxcode.sh if needed. Promo seats are limited; a full list lands on /promo-full.

03

What Boxcode does

Ask in plain English. There is no flag-heavy command for most of this on purpose.

  • Reads, writes, and runs

    It works in the directory you launched from. Destructive actions wait for y/n. Catastrophic commands are never offered.

  • Every file change is a diff

    Approve red and green lines with real line numbers against the file on disk. The preview is produced by the same code that applies the edit.

  • /plan, then write

    Research first. You get an editable plan.md in the project, then approve the approach before any file changes.

  • Publish, auth, a database

    Say “publish this” for a shareable link. Add sign-up, a per-project SQLite file, live-reload, and change requests from the live page.

  • Deploy

    Ask it to deploy to Vercel or Netlify. It detects the framework, builds, and returns a live URL — one approval-gated call.

  • Open endpoints

    Any OpenAI-compatible LLM. /provider picks DeepSeek, OpenAI, or a custom endpoint. Existing DEEPSEEK_API_KEY (and the rest) are picked up automatically.

04

CLI

A native Rust TUI on macOS, Linux, and Windows. Sessions print as ordinary terminal output, so scrollback, selection, and search still work.

Keys

  • EnterSend
  • Alt / Shift-EnterNewline
  • ↑ / ↓Prompt history
  • EscCancel the turn in flight
  • Ctrl-C twiceExit (first press arms it)

Slash commands

Type a slash in the prompt. /provider and /model write ~/.boxcode/config.toml immediately.

  • /planResearch first, then approve a plan before any file changes
  • /providerPick a provider, then a model
  • /modelRe-pick the model for the current provider
  • /loginSign in with Google in the browser, or show status if already linked
  • /logoutClear the local boxcode.sh session and promo key
  • /initExplore the project and write BOXCODE.md
  • /resumeReload this directory's last session
  • /pullSwitch to a different project this machine has published
  • /newStart a fresh conversation (the old one stays on disk for /resume)
  • /compactSummarize a long conversation, freeing context
  • /usageLocal token usage — today, last 7 days, all time
  • /quotaWhat is left today, and any limits you set
  • /rollbackUndo every file the model wrote this session
  • /diffShow everything changed on disk this session
  • /hostedProjects this machine is hosting, and whether they are live
  • /exitLeave boxcode

Approval and rollback

Default approval is destructive only — deletes, force-pushes, publishing, and putting anything on the internet wait for yes, shown in full. Set approval = "always" under [tools] to be asked about every write and command. /rollback restores files the model wrote this session; your own edits are never touched. Shell commands that already ran are named, not pretended away.

CLI product page

05

IDE

Boxcode IDE is a Code-OSS fork. It owns the editor surface only. The agent loop, tools, and approval gate stay in the Rust CLI. Chat launches boxcode --acp and speaks JSON-RPC over stdio — no second agent in TypeScript.

  1. Install order

    CLI on PATH first, then the editor from Downloads. Open a folder and send a message. Ask, Edit, and Agent modes register boxcode as the default chat participant.

  2. macOS quarantine

    Builds are unsigned while the IDE is in development. After dragging to Applications:

    xattr -cr "/Applications/Boxcode IDE.app"

  3. Sign in

    Use Sign in in the IDE, or run boxcode login once. Both write ~/.boxcode/config.toml. The first chat message walks you through a provider and API key if that file is not there yet.

  4. In the editor

    Boxcode Dark and Boxcode Light ship in-tree. An Integrated Browser pane and localhost auto-open keep frontend work in the window.

IDE product page

06

Config

Everything lives under ~/.boxcode/. Env vars override the file.

# ~/.boxcode/config.toml  — written by boxcode login or /provider

[tools]
enabled = true
workspace = "."
approval = "destructive"   # or "always"

[deploy]
enabled = true

[update]
check_on_start = true

[ui]
theme = "auto"             # auto | dark | light
clear_on_exit = true

Point it at your own endpoint without login:

export BOXCODE_ENDPOINT=https://api.deepseek.com
export BOXCODE_MODEL=deepseek-v4-flash
export BOXCODE_API_KEY=…
  • boxcode --upgrade — force-install the latest CLI (also repairs a broken install).
  • BOXCODE_NO_UPDATE_CHECK=1 — skip the startup update prompt.
  • Sessions persist per directory under ~/.boxcode/sessions/. /resume picks up after a crash.
  • BOXCODE.md or AGENTS.md at the project root rides with every request. /init writes one.

07

Account and credits

A new Google account on boxcode.sh gets a lifetime promo credit on llm.boxcode.sh (currently $5). Spend and remaining show on /account after you sign in on the site. The CLI/IDE key is the same promo key boxcode login writes.

Prefer your own provider? Skip login, run /provider, and paste a key. Nothing is hardcoded to one vendor.

08

Reference

Source, releases, and deeper internals stay on GitHub. This page is the day-to-day manual.