# `agentbox`

> `agentbox` prepares a Mac to become a managed, headless OpenClaw host with a running OpenClaw Gateway, reasonable security defaults, and optional Tailscale access.

`agentbox` is a hosted macOS bootstrap script intended to take a fresh Mac to a running OpenClaw Gateway and a host ready for agent workspaces. It targets macOS 26.x on `x64` and `arm64` and requires a sudo-capable admin user plus physical or admin recovery access. Already provisioned Macs are reconciled on a best-effort basis; back up existing accounts, services, and OpenClaw state first because manual intervention may be required.

Linux and Windows are not supported yet. Linux support is planned.

At a high level, `agentbox` installs Homebrew and core dependencies, creates or reuses a non-admin OpenClaw runner user, manages Main as the explicit default inert fallback with a canonical workspace, sets macOS system identity and headless power/time/recovery defaults, enables classic SSH, stages OpenClaw's native user LaunchAgent with runtime-user autologin enabled by default, installs periodic health snapshots and logs, optionally hardens SSH to key-only access, optionally connects the Mac to a Tailscale tailnet, and optionally configures initial OpenClaw model auth. Existing unowned or inconsistently marked Main state requires explicit takeover before replacement.

The optional Codex plugin adds three guided workflows: `$tanaab-agentbox-installer` manages stable and source executables, `$tanaab-agentbox` plans and runs bootstrap or reconciliation, and `$tanaab-agentbox-doctor` reads the fixed agentbox-published health snapshot without sudo and recommends focused remediation for one local installed host. The hosted script remains the primary setup path and does not require Codex.

The advanced reference covers installed components, OpenClaw LaunchAgent and autologin behavior, the full option and environment-variable contract, brewgroup behavior, OpenClaw auth environment handling, Tailscale details, manual verification, and payload resolution. The Codex guide covers plugin installation, workflow ownership, example prompts, and version alignment.

Other agent workspaces layer on top of the host and remain out of scope here: no additional persona setup, dotfiles, project credentials, trading services, app-specific workloads, router port forwarding, or public WAN exposure. Tailscale is recommended for remote access, but setup can be explicitly disabled.

## Primary Resources

- [Hosted macOS script](https://agentbox.tanaab.sh/macos.sh): The generated shell entrypoint for bootstrapping a Mac.
- [Hosted unsupported script](https://agentbox.tanaab.sh/unsupported.sh): The generated fallback for unsupported or unknown platforms.
- [README source](https://raw.githubusercontent.com/tanaabased/agentbox/main/README.md): Main setup path, quickstart, usage, verification, and project links.
- [Advanced source](https://raw.githubusercontent.com/tanaabased/agentbox/main/ADVANCED.md): Installed components, OpenClaw LaunchAgent behavior, full configuration reference, manual verification, and payload-resolution details.
- [Codex plugin source](https://raw.githubusercontent.com/tanaabased/agentbox/main/CODEX.md): Optional plugin installation, bundled workflow ownership, guided diagnosis, and version-alignment details.
- [GitHub repository](https://github.com/tanaabased/agentbox): Source code, canonical docs, workflows, and examples.
- [Releases](https://github.com/tanaabased/agentbox/releases): Published release tags for version-pinned installs.
- [Issues](https://github.com/tanaabased/agentbox/issues): Bug reports, regressions, and feature requests.
- [Bootbox](https://github.com/tanaabased/bootbox): The generic macOS bootstrap layer used by agentbox.