Reference · the tools
The tools
What Claude can do on your box, one page each. These are rendered from the servers themselves — the words below are the words Claude reads — so they cannot say one thing while the box does another.
You do not call these. You say what you want, and Claude picks the tool, fills in the arguments, and tells you what came back. The pages are here so you know what it is working with: what each one does on the box, what it needs to know, and which ones ask first.
Every tool takes an optional box. With one box, Claude never has to name it.
What the connector tells Claude
Sent to every session that connects, wherever it runs — a phone, a laptop, your box. What only a box knows, the box says itself.
Bettik runs <handle>'s environments on their own box. You install, save and
look after them with these tools; the work itself -- editing, npm, git, psql
-- happens in the box's workbench, over ssh or in a session running there.
**Someone new, or unsure what is set up?** Call `get_started` first and
follow the one next step it gives. Claude is signed in on a box from here:
`sign_in_claude` gives a link, <handle> pastes back the code it shows, and
`finish_claude_sign_in` hands it over.
## Ask first
- **`destroy_environment` and `destroy_box`**: confirm with <handle> first,
naming it, unless they just asked for that one. Nothing undoes them.
- **Making an environment public** (`share_environment`): ask, then repeat the address.
- **A saved environment holds its private data**; a version of a template is
what can be shared. Without `go: true` both only say what would happen:
tell <handle>, and go once they say yes.
- **Never stop an environment on your own to make room**: ask.
## Environments
An environment is a directory Docker runs -- usually an app and its database --
published at `https://<environment>.<box>.<handle>.bettik.dev` and
reachable only by people given access. `compose.yaml` is what runs,
`seed` fills it once, `update` brings it current, `start` runs it. Code
lives under `projects/`, one directory per repository. It may be an app, a
game, a kit or one change to a repository; its author says which.
**Cloning is how you get an isolated copy.** `clone_environment` is
copy-on-write: seconds, with `node_modules` and the live database. Not a
git worktree. To try something risky, clone.
**Claim an environment before you change anything in it** (`claim_environment`, a
recognisable `holder`, `session_id` from `bettik-session-id` on a box).
One writer or many readers; a claim never expires. Held by someone else?
Clone, never steal unless <handle> says. `release_environment` when you finish.
## Templates and names
An **environment template** is an environment packed for keeping. `list_templates` shows what
<handle> can install (starter kits, theirs, their families' and
organizations' as `org/name`); `install_environment` fetches one. Say which
template and what it brings; ask when more than one fits. `empty` when the
setup is the work.
**A name becomes the address**, `<name>.<box>.<handle>.bettik.dev`,
which <handle> will type and share for months. Ask them for it, saying why;
do not invent one. If tidying changes it, tell them.
## Room on the box
`environment_status` says how full a box is. Under 75% memory: install and
start freely. Above, the call comes back as a question naming the idlest
environment: put it to <handle>. Under 1 GB free it is a no.
## Renamed
Bundle is now environment, package is template, snapshot is saved environment.
Tools: install/clone/seed/update/bounce/build/stop/start/share/destroy/claim/release/transfer_bundle → *_environment; bundle_status → environment_status, bundle_logs → environment_logs, list_packages → list_templates, fetch_package → fetch_template, delete_package → delete_template, snapshot_bundle → save_environment, release_snapshot → publish_template, release_status → publish_status; bundle_id → environment_id, package → template, snapshot → saved;
~/bundles → ~/environments; _BETTIK_BUNDLE → _BETTIK_ENVIRONMENT. If one
name is missing, try the other.
## More
Each tool's description has the rest; on a box, `~/.bettik/docs/`. When Bettik itself gets in the way, offer `send_feedback`.
Boxes
The machine itself. These belong to your account, not to any one box.
list_boxesYour boxes: name, state, and address.create_boxRequest a new box, within its account's limit: a machine, about six minutes.destroy_boxDestroy one of your boxes: the machine and every environment on it.update_boxTake the newest Bettik release this box has been told about (D70).prune_boxFree Docker's build cache, the images nothing references (dangling), and cached template versions older than the newest of their name, and say what was freed and what the disk is at now.restart_boxRestart one of your boxes: the machine is rebooted through the provider, so it works when the box is too wedged to answer.restart_workbenchRestart the owner's workbench container on this box, in place.Asks firstrestart_claudeRestart Remote Control, the bridge that puts this box in the Claude app, when the box is missing from the app or start_session and wake_session cannot reach it.Asks first
Workspaces
More than one workbench on a box, each with its own container, limits and sign-in.
list_workspacesMain and every other workspace on this box: what signs in there (claude or codex), its CPU and memory limits, whether it is running, whether it is signed in, the account it is signed in to when the box has read it, how to ssh into it (the box's ssh address with the workspace's login, wksp-<name>), and its ~/.claude: blank, or the repository and branch it syncs to.Read-onlyadd_workspaceAdd a workspace to this box: another workbench beside main, with its own container, home, limits and sign-in -- a second Claude account, or Codex.Asks firstremove_workspaceRemove a workspace from this box: its container is stopped, and the box forgets it and which account was signed in there.Asks first
Your configuration
Your Claude settings on the box as a repository you own.
Environments
Installing, running and looking at the environments on a box.
install_environmentInstall a template onto this box as a new environment, and start it.clone_environmentCopy-on-write clone of an existing environment, INCLUDING its database contents and installed dependencies.environment_statusShow the user's environments: state, URLs, memory and CPU in use, and when each was last active, after the box's own memory and disk.Read-onlyenvironment_logsWhat an environment's containers printed: the dev server's output and the database's.Read-onlystart_environmentBring a stopped environment up: its containers come back over the same directory, at the same address, without rebuilding images.stop_environmentStop an environment: its stop script runs if it has one, then its containers come down.build_environmentBuild the environment from its directory as it is now: compose.yaml and bettik.json are re-read, images built or pulled, the containers that changed recreated, .env rewritten, newly declared secrets minted, and the environment is up.bounce_environmentBounce an environment's processes -- all of them, or one service -- without touching the environment.update_environmentRun the environment's own update script: pull each project, reinstall, migrate -- whatever the environment says an update is.seed_environmentRun the environment's seed script now, inside the app container, from blank.share_environmentSet who may open an environment's address.destroy_environmentPermanently delete an environment, its container and ALL of its data, including its database.Asks first
Sessions
Your Claude sessions on the box: what there is, starting one, waking one, talking to one, stopping or archiving one.
list_sessionsThe owner's Claude sessions on this box that they can open on claude.ai or in the Claude app: each one's name, link, directory, and whether it is working, idle, asleep, or restarting.Read-onlystart_sessionStart a new Claude Code session on this box, through its Remote Control bridge -- the same kind of session the owner starts from the Claude app, in their session list, which they can open and drive.wake_sessionBring back a session that list_sessions shows as asleep, so the owner can use it from claude.ai or the app again, with its history.send_to_sessionSend one of the owner's sessions on this box a message, as their next word to it: a question, a change of plan, "carry on".read_sessionWhat one of the owner's sessions on this box was last asked and what it said back -- its words, not its tool calls -- and whether it is still working.Read-onlystop_sessionStop one of the owner's sessions on this box at once, whatever it is doing -- for one that has gone wrong or is running too long.Asks firstarchive_sessionBe done with one of the owner's sessions on this box: it is archived, so it leaves their session list in the Claude app and on claude.ai, and its process on the box ends.Asks first
Gateway
Messages from outside into your sessions: topics, who is subscribed, posting and reading.
list_topicsThe topics on this box's messaging gateway: how many messages each keeps and when the last came, and who gets them -- the sessions subscribed to each, and how many messages each has not had yet.Read-onlysubscribe_topicHave the box deliver a topic's messages.unsubscribe_topicStop delivering a topic to a session: the subscription goes (its number from list_topics).post_to_topicPost a message to a topic on this box's gateway, as any producer would: every session subscribed to it gets it (a sleeping one is woken), and with nobody subscribed it is kept for whoever subscribes.read_topicRead the messages on a topic, oldest first.make_topic_tokenMake a token a producer outside the box -- Cue, an email or webhook service, CI -- uses to post to this box's gateway: POST https://gateway.<this box>.<domain>/topics/<topic> with `Authorization: Bearer <token>`, or -- for a webhook whose sender lets you set only a URL (Jira, GitHub, Stripe) -- POST .../hooks/<token>/<topic>.revoke_topic_tokenTake back every token made for a producer: its posts are refused from now on.
Timers
The box posting to a gateway topic at a time: every weekday at 7:30, or once at 3pm.
list_timersThe box's timers: each one's schedule and time zone, the topic it posts to and what it says, when it next fires and last fired, and whether it is paused.Read-onlyadd_timerHave the box post a message to a gateway topic at a time: repeating (cron, five fields: minute hour day-of-month month day-of-week -- "30 7 * * 1-5" is weekdays at 7:30) or once (at).change_timerPause a timer (it stays, and fires nothing), resume it (from its next time after now; nothing it missed while paused fires), remove it, or change its zone (action zone, with tz).
Cue
Calls with Claude on the box from your phone: taking the box off Cue.
Who is working on what
Claims: how sessions keep out of each other’s way.
Templates
What you can install, saving an environment, and publishing a version of a template.
list_templatesEvery template you can install: the starter kits that come with Bettik, your own templates, and those of each family or organization you are in ("org/name").Read-onlyfetch_templateFetch a template onto a box without installing it: it waits there, out of sight, and a later install_environment of it takes seconds instead of a download.save_environmentSave a running environment, in one step: the environment is stopped for a few seconds, its directory is kept -- compose.yaml, the scripts, projects/ with dependencies and git history, and its data as it is -- as the template's next saved environment (name@s3), and the environment starts again.publish_templatePublish a saved environment as a version of its template: a clean copy that can be shared.publish_statusHow a template's versions are going: the newest few, each ready, building (and at which step) or stopped, with why -- the scan's findings, a failed test install -- what it left out, and its commits.Read-onlydelete_templateDelete one of your templates.Asks first
Also
switch_boxMake one of your boxes your current box: the one every box tool acts on when a call does not name a box.get_startedWhere the user stands on Bettik and the one next step: whether they have a box, whether it is still being made, and whether Claude is signed in on it.Read-onlyaccept_inviteJoin a family or organization that invited the address the user signs in with, as get_started lists them.sign_in_claudeSign Claude in on a box, so Claude sessions can run there and the box shows in the Claude app.finish_claude_sign_inThe second half of sign_in_claude: hand the box the code the user was shown after opening the link.send_feedbackTell the Bettik team about Bettik itself: a tool that failed or said something wrong, a step that was confusing or took too many calls, something missing.time_zoneThe person's time zones: where they live (home), and where they are for now (current), until a date if they say.session_backupWhere an account's boxes copy their Claude sessions (D-session-backup): the account's own S3 bucket, set once for every box it owns, boxes made later included.set_session_backupSet where an account's boxes copy their Claude sessions: an S3 bucket, its region, the role boxes take on (made as session_backup describes), and each box's folder.test_session_backupCheck an account's session backup works, as a box will: Bettik signs as a pretend box "bettik-test" of the account, takes on the role, and adds one small file, bettik-test.txt, under the folder.clear_session_backupTurn off session backup for an account: its boxes stop copying.
How to read a tool page
Read-only tools change nothing. Asks first marks the ones that delete: a session on the box has every tool pre-approved except those, and Claude confirms with you before calling one, naming the thing it is about to remove. The rest create, start, stop or copy — reversible, or at least not losses.