openpalm

@openpalm/cli

Bun CLI for bootstrapping and managing an OpenPalm installation. The CLI is the primary orchestrator -- all commands work without the admin container. When admin is running, commands optionally delegate to the admin API.

Self-Sufficient Mode

The CLI operates directly against Docker Compose without requiring an admin container:

• Install -- creates the ~/.openpalm/ home layout, downloads assets, serves the setup wizard locally via Bun.serve(), writes files to their final locations, and starts core services
• All lifecycle commands -- refresh files in ~/.openpalm/ when needed, then run Docker Compose directly
• Admin delegation -- the install command checks for a running admin and delegates if reachable. Other commands operate directly via Docker Compose.

The admin container is optional. Use --with-admin to enable the admin addon overlay in the compose file set.

Commands

Command	Description
openpalm install	Bootstrap ~/.openpalm/, download assets, run setup wizard, start core services
openpalm uninstall	Stop and remove the stack (preserves config and data)
openpalm update	Pull latest images and recreate containers
openpalm upgrade	Alias for update
openpalm self-update	Replace the installed CLI binary with the latest release build
`openpalm addon <enable	disable
`openpalm admin <enable	disable
openpalm start [svc...]	Start all or named services
openpalm start --with-admin	Start all services including admin UI and docker-socket-proxy
openpalm stop [svc...]	Stop all or named services
openpalm restart [svc...]	Restart all or named services
openpalm logs [svc...]	Tail last 100 log lines
openpalm status	Show container status
openpalm service <sub> [svc...]	Alias -- subcommands: start, stop, restart, logs, status, update
openpalm validate	Validate vault env files against their schemas (requires prior install)
openpalm scan	Scan for leaked secrets in config files

Install options

--force skip "already installed" check and create a backup of the current OP_HOME, --version TAG install a specific ref (default: current CLI version), --no-start prepare files only, --no-open skip browser launch.

Admin addon

Admin and docker-socket-proxy start only when explicitly requested:

openpalm admin enable           # Enable the admin addon and start its services
openpalm admin disable          # Stop and disable the admin addon
openpalm admin status           # Show whether the admin addon is enabled
openpalm addon enable chat      # Enable a registry addon and start its services
openpalm addon disable chat     # Stop and disable a registry addon
openpalm addon list             # Show available addons and whether they are enabled

Setup Wizard

On first install, the CLI serves a setup wizard on port 8100 via Bun.serve(). That temporary setup port is separate from the admin container, which defaults to http://localhost:3880 once installed. The wizard runs entirely in the browser (vanilla HTML/JS) and calls performSetup() from @openpalm/lib to write secrets, connection profiles, memory config, and other files to their final locations. No admin container is involved.

Environment Variables

Variable	Default	Purpose
OP_HOME	~/.openpalm	Root of all OpenPalm state
OP_WORK_DIR	~/openpalm	Assistant working directory
OP_ADMIN_API_URL	http://localhost:3880	Admin API endpoint (for optional delegation)
OP_ADMIN_TOKEN	(from vault/stack/stack.env)	Admin API auth token

How It Works

• Bootstrap (first install) -- creates the ~/.openpalm/ tree, downloads core assets from GitHub, seeds vault/user/user.env and vault/stack/stack.env, materializes the runtime registry catalog under registry/, serves the setup wizard, writes stack/core.compose.yml, enables requested addons under stack/addons/, and starts core services via docker compose up
• Running stack -- commands refresh files in ~/.openpalm/ when needed, then execute Docker Compose directly.
• Admin absent -- all commands work identically. Admin is never required for any operation.

Follows the file-assembly principle: copies whole files, never renders templates. See core-principles.md.

Building

bun run build                  # Current platform -> dist/openpalm-cli
bun run build:linux-x64        # Cross-compile (also: linux-arm64, darwin-x64, darwin-arm64, windows-x64, windows-arm64)

Development

cd packages/cli
bun run start -- install --no-start
bun test

See also: scripts/setup.sh and scripts/setup.ps1. Both installers support --cli-only when you only want to install or refresh the CLI binary without touching the stack or OP_HOME.