# Machines & Workspaces

Orb and sandboxed.sh execute agent missions across three machine tiers while keeping all project state, transcripts, and `@context` files unified on the Core server.

## 1. Execution Placements

| Placement | Target | How it runs |
| --- | --- | --- |
| **This computer** (`placement: "client"`) | Your macOS desktop running Orb | Orb's Tauri runner spawns your locally installed CLI (`claude`, `codex`, `agy`, `opencode`, `grok`) in `~/.orb/local-runs/<mission-id>` (or a chosen checkout). Uses your local credentials and streams events back to Core. Supports offline starts (`POST /api/control/local-origins`). |
| **Core** (`core`) | The main `sandboxed-sh` Linux server | Runs in a per-mission directory inside either a **Host workspace** or an isolated **Container workspace** (`systemd-nspawn`). |
| **Remote Fleet Nodes** (`remote_node_id`) | Dedicated Linux / GPU / ARM servers running `sandboxed-node` | Core dispatches leased jobs over HTTPS (port `3088`) using per-mission lease tokens signed with the node's secret. Nodes stream events back to Core and synchronize `@context` replicas. |
| **Cloud Agents** | Hermes, Grok Bot, Cursor Cloud | Core's cloud adapters drive external coordinator or provider sessions and record durable turn receipts in the same project database. |

## 2. Core & Node Workspace Types

### Host Workspace
Commands run directly on the server or node inside a per-mission working directory (`workspaces/mission-<short-id>` or `MISSION_WORKSPACE_ROOT`). Built-in bash (`bash` / `Bash`) executes natively inside that directory.

### Container Workspace (`systemd-nspawn`)
Isolated Linux rootfs built with `debootstrap` (Ubuntu 24.04 `ubuntu-noble`, Ubuntu 22.04 `ubuntu-jammy`, Debian 12 `debian-bookworm`, or Arch Linux `arch-linux`).
- **Native execution**: Harnesses and their stdio MCP launchers run *inside* the container via `systemd-nspawn`, so file edits, Git operations, and bash commands never touch the host.
- **Shared project context**: Container workspaces bind-mount only their project's live context directory at `/run/sandboxed-context/<project>`.
- **Disk-backed `/tmp`**: Stock `systemd-nspawn` mounts `/tmp` as a 10%-RAM tmpfs. Set `SANDBOXED_SH_CONTAINER_TMP_ROOT` on the host to back each container's `/tmp` with a persistent disk directory and avoid silent `ENOSPC` failures on large builds.

## 3. Resource Isolation (`missions.slice` cgroups)

To prevent heavy builds (such as parallel Rust or Lean proof compilation) from starving the API or SSE stream, every server mission runs in a transient systemd scope under `missions.slice`, a sibling of `system.slice`:

- **Slice-level protection**: `missions.slice` runs at a lower `CPUWeight` than the API service and enforces aggregate memory ceilings.
- **Per-mission caps**: Configure `MISSION_MEMORY_MAX`, `MISSION_MEMORY_HIGH`, `MISSION_MEMORY_SWAP_MAX`, `MISSION_CPU_WEIGHT`, and `MISSION_CPU_QUOTA`, or adjust them live via `POST /api/workspaces/:id/resources`.

## 4. Remote Fleet Nodes & Spark Build Offload

Fleet nodes run the `sandboxed-node` binary and advertise their installed harnesses, protocol capabilities (`remote_launch`), and disk budgets via `GET /api/remote-nodes`.

- **Managed Fleet Harnesses**: Nodes maintain atomic, integrity-checked CLI installations under `/opt/sandboxed-tools/<harness>/<version>/` via `update-node-harnesses.py`, viewable and updatable from **Orb → Machines → Agent software** (`GET /api/software`, `POST /api/software/updates`).
- **DGX Spark Offload (`spark-build`)**: For memory-intensive Lean 4 / proof builds, harnesses invoke `spark-build`, which routes through `/api/spark/offload` to `dgx-spark-arbiter` without exposing node SSH keys inside the workspace.

## 5. Moving a Mission Across Machines (`Change machine…`)

You can move an existing idle mission between **This computer**, **Core**, and any online **Fleet node** from the mission footer (**Change machine…** → `GET/POST /api/control/missions/:id/machine-transfer`):

1. **Inventory & Selection**: Orb previews the workspace size and files. Build artifacts (`target/`, `node_modules/`, `.lake/`), toolchains, and credentials are excluded by default (you can toggle ignored folders if needed).
2. **Verified Checkpoint Transfer**: Files transfer in 1 MiB blocks with a SHA-256 manifest (up to 10 GiB / 50,000 files). Git repositories travel as Git bundles with uncommitted working-tree overlays, and internal relative symlinks are preserved.
3. **Generation Fence**: Activation commits the new placement in SQLite under a compare-and-swap generation fence. The mission keeps its UUID, project, and transcript, and starts a fresh native harness session on the destination machine with portable conversation history.