> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Share a VM

> Open a machine to your whole org with one command — with a clean credential handoff every time.

Sharing makes one of your machines reachable by every member of your organization. It's a single command, it's owner-controlled, and it's reversible.

```bash theme={"theme":"github-dark"}
boxd machine share staging         # every member of the org can now connect
boxd machine unshare staging       # back to private — yours alone again
```

Once shared, any member runs `boxd connect staging` (or SSHes in) and lands on the same machine — same disk, same running services, same data. The org keeps paying for it the whole time; unsharing only changes **who can reach it**, never who's billed.

<Note color="#E05A6D">
  **"Make this VM public" means "share it with the org."** The machine's `https://name.boxd.sh` URL is already public to the internet — sharing is about which **teammates** can get a shell on the box, not about exposing a web app.
</Note>

## The credential handoff

A machine you've been working on holds your personal agent logins on disk — Claude Code, Codex, and OpenCode keep their tokens in your home directory. The moment a machine becomes reachable by the rest of your team, those tokens must not be sitting there for anyone with a shell to read.

boxd enforces this for you. **Sharing a machine wipes the in-VM agent credentials the instant it goes shared** — immediately, no reboot required:

```text theme={"theme":"github-dark"}
~/.claude/.credentials.json          # Claude Code
~/.codex/auth.json                   # Codex
~/.local/share/opencode/auth.json    # OpenCode
```

While the machine stays shared, these are never written back and never synced anywhere — so a login on a shared machine can't leak onto your other personal machines either. The machine's GitHub access also switches from your personal token to the **organization's GitHub App** token, so repo access on a shared box is the org's, not yours.

This is the guarantee: **no member's personal login is ever left readable on a machine the rest of the team can reach.** Sharing is a clean handoff, every time.

### Unsharing restores you

Run `boxd machine unshare` and the machine is private to you again — and your agents come back:

* **Claude Code re-authenticates automatically.** boxd restores your Claude login on the next session; you don't have to do anything.
* **Codex and OpenCode** need a **one-time** `codex` / `opencode` login on the machine. After that they persist normally again — a private machine is never wiped.

<Warning>
  **Don't share the machine an agent is actively working inside.** Sharing wipes credentials live, so a Claude Code (or Codex / OpenCode) session running *in that machine* is logged out mid-task. If you need to share a box an agent is using, make it the **last** step of the run, or share a different idle machine — and expect to re-authenticate afterward.
</Warning>

## Fork a shared machine for private work

Forking a shared machine gives you a **private fork by default** — the org keeps paying, but the copy is yours alone, and your agent logins work in it again right away:

```bash theme={"theme":"github-dark"}
boxd machine fork staging            # private fork: org-billed, yours alone, logins restored
boxd machine fork staging --shared   # keep the fork shared with the whole org instead
```

Because a private fork isn't reachable by the team, it's never wiped: Claude Code restores automatically, and a one-time Codex / OpenCode login sticks. This is the clean way to take a shared golden machine and do focused, authenticated work on a copy without touching the shared original. Pass `--shared` when you want the fork to stay open to the org. (Forking a personal machine is unchanged — the fork stays personal.)

## At a glance

| You run                                  | Reachable by | Billed to | In-VM agent logins                                 |
| ---------------------------------------- | ------------ | --------- | -------------------------------------------------- |
| `boxd machine share <vm>`                | Whole org    | Org       | Wiped on share; GitHub → org App token             |
| `boxd machine unshare <vm>`              | You only     | Org       | Claude auto-restores; Codex/OpenCode re-login once |
| `boxd machine fork <shared-vm>`          | You only     | Org       | Restored (private fork)                            |
| `boxd machine fork <shared-vm> --shared` | Whole org    | Org       | Wiped (stays shared)                               |

See the [CLI reference](/reference/external-cli#organizations) for every flag, and [Organizations](/organizations/overview) for the billing and context model.