Start an agent
Start an agent asks where it runs, who it works as, which agent, and its first message.
| Choice | What you pick |
|---|---|
| Where | On a host: a Linux host whose agent was installed with --allow-host-control, up to date and online. Or in a box on a repository (see boxes). |
| Who it works as | root, or a user the host already has who can log in. The agent runs with that user's rights, from its login shell. |
| Folder | A folder that user can open. |
| The agent | Claude Code, Codex, Gemini CLI, OpenCode, Amp or Pi, as installed for that user. Not installed yet? BasePit runs the agent's own install line, as its vendor gives it, as that user, and you watch it. |
| Its first message | What you want done, in plain text. |
The start sheet lists your other hosts and why each one cannot run an agent: installed without --allow-host-control, out of date, a Mac, offline, or powered off.
Asking first, or working alone
You approve each step
It stops before each command and asks you, and you answer in BasePit with a button.
It runs what it decides
It runs every command it decides on, and stops only when it is done or stuck. BasePit says plainly that it will run every command as that user, on that host, with nobody approving.
- Claude Code also offers Auto, where its own classifier approves each command instead of a person. BasePit says that it is not a person reviewing. Claude Code will not work alone as root.
- Codex runs read-only commands by itself and asks before anything else.
- An agent that never asks before it runs a command can only work alone, and the start sheet says so.
Watch and answer
- Each session has a page with its live terminal, and a state: Working, Wants you, Paused or Ended. The sidebar shows when one wants you.
- When the agent asks a question, its choices become buttons. A button presses only the question you saw: if the question changed meanwhile, BasePit says so and asks you to read it again.
- Send a message to tell it what to do next: plain text, at most 8 KiB.
- A session keeps running between your visits, and through BasePit's own agent restarting or upgrading.
- Stop ends the session. What it changed in the folder stays, and its last screen is kept for 24 hours.
- Admins start and stop agents. Operators can watch a session and read its question; Viewers see that a session exists, not its screen.
What it changed
What it changed reads the folder's Git checkout: the branch, the files changed with lines added and removed, the commits since it started, and what is not committed yet.
Ask it to sends one of four fixed messages into the session:
| Ask | What happens |
|---|---|
| Commit | It commits its work. |
| Commit and push | In a box: it commits, and BasePit pushes the branch. |
| Review the changes | It reviews what it changed. Changes nothing. |
| Write a recap | It writes a summary of what it did. Changes nothing. |
Hand off to another agent
Move the work to a different agent without losing its thread. BasePit writes what the first agent did into .basepit/handoff.md, from its own record of the session, and keeps that file out of Git. The new agent starts in the same folder as the same user, with the note to read.
- Keep the first session running, or stop it once the new agent starts.
- For an agent that keeps no record BasePit can read, the note holds the last 400 lines of its terminal.
Boxes on a Git branch
A box is a container BasePit makes on an opted-in host, from the platform's own image pinned by digest, holding a copy of one of your Git sources on a new branch. The agent works there, not in a folder of the host.
- BasePit pushes the box's branch, using the Git source's write credential (added in Sources › Git).
- The Git token goes only to a short-lived helper container, never into the box where the AI works.
- A box whose session has been quiet for 15 minutes is paused, and resumes when you need it.
- A host needs Docker to hold a box.
Keys, sign-in and usage
- Keys: a key you set is sealed the moment you set it and never shown again. BasePit gives it only to the agent that reads it from its environment, and only in that session.
- Sign-in: with no key set, an agent that signs in inside its own terminal does so there, and BasePit gives it no key.
- Usage is read every hour from Claude Code's and Codex's own logs on each host.
- Agent time uses credits only while a session is live, by the hour. Pricing.
The boundary
An AI coding agent's session is one of six features that open a session into a machine, and it keeps the same edges as the others. See Security.
- Only on a Linux host whose owner installed the agent with
--allow-host-control. - What runs is the agent's own program, started with flags from a fixed table that BasePit and the host's agent share. A message you type is never turned into a flag, and a first message cannot start with a dash.
- Not a byte of a session is logged.
- Starting, stopping and handing off sessions are recorded in Activity.
Limits
- Linux hosts only: agents do not run on a Mac or a worker.
- At most 8 agent sessions and 4 boxes on one host.
- What it changed reads only the folder's Git checkout. Changes the agent made elsewhere on the host are not shown there.
- In Works alone, nobody approves the commands. Choose the user it works as accordingly.
- If your credits run out and the grace period ends, AI agents pause until you top up. Your apps, and everything else, keep running.