Reference · on the box · environments

On the box: working in an environment

For a session on a box: where things are, how to step into an environment, and how to share the box's room. The workbench and The environment directory are the same ground for the person.

Where things are

Each running environment is a directory, ~/environments/<name>:

/home/user/                    ~ — you start here. It is the person's, and it persists.
  .claude/                     their Claude settings, skills and memory — theirs, not the box's
  .bettik/                     what the box delivers: env vars, as files; docs/, Bettik's docs
  scratch/                     anything not tied to an environment
  public/                      PUBLIC: anyone with a file's link can open it
  environments/<name>/         one environment
    .env                       DATABASE_URL and the environment's address, rewritten on every start
    projects/<name>/           the repositories — this is where code lives
    initdb/                    SQL that runs once, on a new database
    pgdata/                    Postgres data. Never edit this by hand.

~/.claude is where Claude Code reads the person's own configuration, and the box never writes into it. Before you change anything there, look: it may be a git repository they keep.

An environment may hold several repositories under projects/. That is normal -- a site and an API side by side.

Stepping into an environment

You start in ~, inside no environment. /bettik-environment <name> puts you in one: it claims the environment, moves you to ~/environments/<name>, and reads the environment's own .env and CLAUDE.md. From then on you work there as in any repository. /bettik-environment new <name> installs one and does the same; /bettik-environment leave releases it and brings you back. /bettik-try <url> turns a repository into a running environment.

Most environments you find already belong to somebody's session. That is why the usual move is to install or clone your own rather than step into one.

Room on the box

Memory is what limits how many environments run, and environment_status says how full the box is. Under 75%: install and start freely. Above it, an install or start comes back as a question naming the idlest running environment -- put that to the person and do what they say. Do not stop an environment on your own to make room. Environments have a memory limit each; two heavy builds at once is a bad idea. save_environment and then destroy_environment frees the room and keeps the environment as a saved environment, to install again later.

Worth knowing

• Everything under ~ survives restarts and redeploys. Nothing outside it does -- the container is rebuilt regularly.
• People reach the box with their own SSH client and VS Code Remote SSH. There is no web editor or web terminal, and no port to expose: an environment's address is served through the box's tunnel, by a gate that checks who is asking.
• destroy_box exists on the connector but not from a session running on the box it names -- it would end that session. A box is destroyed from the dashboard, or from a session somewhere else.
• bettik-guide prints the box's instructions; bettik-session-id prints this session's id for a claim.