agentbox

agentbox prepares a Mac to become a managed, headless OpenClaw host, optionally connected to your Tailscale tailnet. Its goal is to take a fresh box from zero to a running OpenClaw Gateway with reasonable security defaults and a host ready for agent workspaces.

Supports macOS 26.x on x64 and arm64. Requires a sudo-capable admin user and physical or admin recovery access. Intended environment: a fresh Mac dedicated to the OpenClaw host role. On an already provisioned Mac, agentbox reconciles its managed surfaces on a best-effort basis. Back up first; existing accounts, services, or OpenClaw state may require manual intervention, and your mileage may vary.

Platform note: Linux and Windows are not supported yet; Linux support is planned.

agentbox takes ownership of OpenClaw's main agent, makes it the explicit default, and seeds ~/.openclaw/workspace-agentbox-main as an inert fallback that routes users toward more appropriate agents. Existing unowned or inconsistently marked Main state requires the explicit --openclaw-takeover-main gate before agentbox replaces it.

Important

agentbox currently pins the Homebrew OpenClaw CLI to 2026.7.1 for compatibility. It does not install the latest OpenClaw release or automatically change an existing different version.

Overview

At a high level, agentbox:

• installs Homebrew and core dependencies from Brewfile
• creates or reuses a non-admin OpenClaw runner user
• sets macOS system identity and headless power, time, and recovery defaults
• enables classic SSH
• stages OpenClaw's native user LaunchAgent and enables runtime-user autologin by default
• owns OpenClaw Main as an inert fallback with a managed workspace, identity, and routing policy
• installs health checks and logs for post-bootstrap verification
• optionally installs SSH public keys and hardens SSH to key-only access
• optionally runs a managed tailscaled daemon and connects the Mac to a tailnet
• optionally configures initial OpenClaw model auth

For a more complete look at installed components, see ADVANCED.md#what-gets-installed.

Quickstart

Complete the Preflight Checks first, then run the hosted bootstrap on the Mac you are preparing:

/bin/bash -c "$(curl -fsSL https://agentbox.tanaab.sh/macos.sh)" agentbox \
  --tailscale-authkey "$TS_AUTHKEY" \
  --openclaw-identity "A Tanaab-based Claw <openclaw>" \
  --openclaw-password "$OPENCLAW_PASSWORD"

The OpenClaw runner password is used only when creating the runner account or configuring autologin. agentbox never prints, persists, generates, or debug-logs that password. Autologin is enabled by default so the Gateway returns after reboot; this reduces physical-access security even though the runner remains non-admin. FileVault is incompatible with this unattended-recovery profile.

For the complete option and environment-variable contract, run:

/bin/bash -c "$(curl -fsSL https://agentbox.tanaab.sh/macos.sh)" agentbox --help

Codex is optional. For guided executable management, bootstrap or reconciliation, and host-health diagnosis, see the Codex plugin guide.

Usage

For repeated use, install the hosted script as a local command in a directory you manage on PATH:

mkdir -p "$HOME/.local/bin"
curl -fsSL https://agentbox.tanaab.sh/macos.sh -o "$HOME/.local/bin/agentbox"
chmod +x "$HOME/.local/bin/agentbox"

agentbox --help

Run it with flags when you want to keep the command explicit:

agentbox \
  --tailscale-authkey "$TS_AUTHKEY" \
  --openclaw-password "$OPENCLAW_PASSWORD" \
  --hostname TANAABAGENTBOX1

Common inputs:

Option	Environment variable	Description
--hostname	AGENTBOX_HOSTNAME	macOS hostname and Tailscale hostname source.
--tailscale-authkey	AGENTBOX_TAILSCALE_AUTHKEY	Tailscale auth key for first join; use off, false, no, 0, or null to skip Tailscale setup.
--authorized-key	AGENTBOX_AUTHORIZED_KEY	Public SSH key or public-key file path; providing keys also enables key-only SSH hardening.
--openclaw-password	AGENTBOX_OPENCLAW_PASSWORD	Password used only for OpenClaw runner creation or autologin.
--openclaw-identity	AGENTBOX_OPENCLAW_IDENTITY	OpenClaw runner identity in Full Name <shortname> syntax.
--openclaw-autologin	AGENTBOX_OPENCLAW_AUTOLOGIN	Runtime-user autologin: on or off; defaults to on for unattended reboot recovery.
--openclaw-auth-choice	AGENTBOX_OPENCLAW_AUTH_CHOICE	Initial OpenClaw model auth choice; defaults to skip.
--openclaw-takeover-main	AGENTBOX_OPENCLAW_TAKEOVER_MAIN	Allow agentbox to replace existing unowned Main state after backing up its configuration.
--brewfile	AGENTBOX_BREWFILE	Extra Brewfile sources to append after the core agentbox Brewfile.
--yes	NONINTERACTIVE	Skip interactive prompts.
--debug	AGENTBOX_DEBUG	Show debug output with secrets masked.

Use ADVANCED.md for the full option guide, payload-resolution details, brewgroup behavior, OpenClaw auth environment handling, and deeper Tailscale notes.

Verification

At the end of setup, agentbox prints a concise health success or failure status. A failed health check exits nonzero and prints the report command below; --debug includes the full health report in the setup output.

When the optional Codex plugin is installed, the preferred guided verification path is to run Codex on the local agentbox host and ask:

Use $tanaab-agentbox-doctor to inspect this local agentbox host.

The doctor reads agentbox's administrator-readable health snapshot without sudo, presents grouped status, and recommends focused repairs without applying them. Reboot the Mac, confirm the dedicated runtime user logs in automatically and the native Gateway returns healthy, then rerun the doctor.

Without Codex, use the installed health script directly:

sudo /opt/tanaab/agentbox/bin/health.sh --check
sudo /opt/tanaab/agentbox/bin/health.sh --report

--check exits nonzero when required checks fail. --report prints the same line-oriented report without failing so it can be collected for troubleshooting.

See ADVANCED.md#verification-details for the periodic log, manual follow-up checks, and direct report interpretation.

Optional Codex Plugin

The optional plugin layers three guided workflows over the same bootstrap and installed health contracts:

• $tanaab-agentbox-installer installs or selects stable and source agentbox executables.
• $tanaab-agentbox plans and runs bootstrap or reconciliation with the selected executable.
• $tanaab-agentbox-doctor inspects one local host and recommends focused remediation.

The hosted script remains the primary setup path and does not require Codex. See CODEX.md for plugin installation, example prompts, workflow boundaries, and version alignment.

Development

This repo uses Bun for repo-local tooling and publishes a Netlify-ready dist/ directory.

git clone https://github.com/tanaabased/agentbox.git
cd agentbox
bun install
bun run lint

bun run build regenerates dist/ for release-shaped verification. Local agents should not run it or edit dist/ unless the task explicitly requires generated output.

Leia examples run in GitHub Actions on fresh macOS runners because the mutating scenarios configure system settings, Homebrew packages, SSH, launchd, and Tailscale.

Issues, Questions and Support

Use the GitHub issue queue for bugs, regressions, or feature requests.

Changelog

See CHANGELOG.md for release history and GitHub releases for published artifacts.

Maintainers

• @pirog

Contributors

Made with contrib.rocks.