OpenClaw Hyperlift Template

A ready-to-deploy OpenClaw agent gateway for Spaceship Hyperlift. Deploy to run a hosted AI agent with a web control UI. The agent's workspace — its memory, personality, and configuration — persists on the deployment's volume, and can optionally sync to a branch of your own GitHub repository so you can edit it from your machine and keep your own backup.

What's included

On boot, the container starts an OpenClaw gateway — a web control UI and chat interface for your agent — with a standard OpenClaw agent workspace (the agent's memory, identity, rules, and config). On its first run the agent introduces itself and sets up its identity with you, guided by a BOOTSTRAP.md ritual it then deletes.

On top of that, this template adds a git-sync skill and a sync-status hook, used only when git sync is enabled.

Note: The seed/ directory bootstraps the workspace only on first boot — editing it has no effect on an already-running deployment. To change a running deployment, see Editing the configuration.

Deploy to Hyperlift

Create a Hyperlift app from this template; Hyperlift builds the container from the Dockerfile. On first install it asks you to pick a model provider and enter its API key, and to set a gateway password; both are stored as the app's environment variables. The optional variables you add to the app's environment yourself.

Variable	Set	Purpose
<provider>_API_KEY	Prompted on install	API key for the model provider you pick during install — e.g. OPENAI_API_KEY or ANTHROPIC_API_KEY. See Configure your model provider.
OPENCLAW_GATEWAY_PASSWORD	Prompted on install	Password for the gateway and its control UI.
WORKSPACE_GIT_URL	Optional	Enables git sync — the HTTPS URL of the repository to sync the agent's workspace to. See Git sync.
WORKSPACE_GIT_TOKEN	Optional	GitHub token for git sync, paired with WORKSPACE_GIT_URL.

See the configuration reference for openclaw.json options.

Note: The agent's data lives at /home/node/.openclaw on the app's persistent volume. Leave OPENCLAW_STATE_DIR at its default — pointing it outside /home/node means the data won't survive a restart.

Log in

1. Open the app URL, enter your gateway password in the Password field and click Connect.
2. The first time from a new browser you get a red Device pairing required box with CLI instructions. Ignore the instructions: the template's device-autopair plugin approves the browser within a few seconds. Click Connect once more and you are in.
3. The browser does not store the password, so a new session asks for it again. The pairing is remembered per browser.

On the first visit the control UI may open Model Setup instead of the chat, or the model picker may say No models available. Your provider's key is already there: click Test & use (or Check model when a model is already selected), and once it verifies the model you can start chatting.

Configure your model provider

The template ships with six providers enabled and tested — Anthropic, Google, Mistral, OpenAI, OpenRouter, and xAI. Using one of these is the easy path; any other provider takes a few extra steps on the running deployment. (Mistral is not part of the OpenClaw image, so this template's Dockerfile adds the official @openclaw/mistral-provider package to it.)

A preconfigured provider (recommended)

Pick your provider when you create the app and enter its API key. Its plugin is already on, so its models show up in the control UI — set the agent's default under Settings → Agents & Tools → Models → Default model and Save (or let the first-run Model Setup page do it). That's all. The Chat model control next to the message box only overrides the model for the current chat.

To switch to a different one of the six later, add that provider's key (e.g. ANTHROPIC_API_KEY) in the Hyperlift manager and select its model under Settings → Agents & Tools → Models.

Another provider

OpenClaw supports many more providers; you just enable and configure them yourself. The full list and per-provider settings are in the OpenClaw provider docs.

Recommended — run onboarding from the chat. This template enables the /bash command in the web chat, which runs commands inside the container (Hyperlift gives no SSH access, so this is how you run commands in the deployment). Most extra providers ship as separate packages, so the flow is: add your provider's API key in the Hyperlift manager, install its plugin, then run onboard — it configures the plugin, populates the model catalog, and sets the agent's default model in one step. For Cerebras:

/bash openclaw plugins install @openclaw/cerebras-provider --accept-capabilities
/bash openclaw onboard --auth-choice cerebras-api-key --cerebras-api-key "$CEREBRAS_API_KEY" --gateway-auth=password --gateway-password="\${OPENCLAW_GATEWAY_PASSWORD}" --gateway-bind=lan --skip-skills --skip-ui --accept-risk --non-interactive

• Swap --auth-choice and --<provider>-api-key for your provider — the provider docs list the exact names.
• The --gateway-* flags matter even though Hyperlift already sets these: without them, onboard rewrites your gateway auth to a generated token and the password stops working. The escaped \$ is intentional — it stores ${OPENCLAW_GATEWAY_PASSWORD} in openclaw.json as a reference that OpenClaw resolves from the environment at runtime, so the real password never lands in the file.
• --accept-risk and --non-interactive let it run unattended from the chat.

Alternative — configure it by hand. Edit the live openclaw.json and:

1. Install the plugin: /bash openclaw plugins install @openclaw/<provider>-provider --accept-capabilities (installing also enables it; the six preconfigured providers are already built into the image).
2. Add the provider's API key as an environment variable in the Hyperlift manager.
3. If its models don't appear, add them by hand under models.providers and set agents.defaults.model — the provider docs include a sample config for each.
4. Still not working? Restart the app from the Hyperlift manager; if it persists, see Troubleshooting.

For most providers, steps 1–2 are enough.

Editing the configuration

Almost everything about the deployment lives in openclaw.json — the model, enabled plugins and skills, agent behavior, and gateway settings — so you'll change it regularly as you customize. The easiest way is to just ask the agent; there are five methods in all, and every one changes the live instance:

Method	Where	Good for
Ask the agent	Plain language in the web chat	The simplest and most common approach — say what you want ("enable the Cerebras plugin", "switch to model X", "add a skill for Y") and the agent edits openclaw.json and applies it for you. It runs inside the container, so it can't set Hyperlift env vars — add API keys there yourself.
Control UI — raw config editor	Settings → System → Advanced in the gateway, then switch the editor to Raw	Editing openclaw.json by hand from the browser; nothing to install. Reveal the redacted values with the eye button before editing, then Save.
/bash in the web chat	Type /bash openclaw … in the chat	Running OpenClaw commands inside the container yourself — onboard, plugins enable, config set. They take effect on the deployment.
Git-sync branch	The workspace-sync branch, edited from your machine	Versioned, off-cluster edits to openclaw.json and workspace files. Requires git sync.
Remote CLI	The openclaw CLI on your machine	Operating the gateway (health, logs, messaging) — not config: config/plugins/onboard run locally, not on the deployment. See Remote CLI limitations.

Pick whichever suits the change — the model-provider steps above, for example, use /bash (onboarding) or the raw config editor (manual edits). Whichever you use, keep secrets out of openclaw.json — see Security.

Persistent storage

Hyperlift mounts a persistent volume at /home/node. The deployment uses OpenClaw's defaults — OPENCLAW_STATE_DIR=/home/node/.openclaw and OPENCLAW_CONFIG_PATH=/home/node/.openclaw/openclaw.json — so the agent's state lives on that volume, and anything written under /home/node at runtime persists across restarts and redeploys.

The same mount has a build-time implication for customizing this template: at runtime the volume mounts over whatever the image has at /home/node, so anything a Dockerfile RUN step writes there — directly or as a side effect — is hidden by the mount at runtime. For example:

• RUN openclaw plugins install clawhub:@openclaw/diagnostics-otel — writes plugins, extensions, and config under /home/node/.openclaw
• RUN openclaw skills install calendar — writes skills to /home/node/.openclaw/workspace/skills

Installing ordinary system packages (jq, wget, tree, …) in the Dockerfile works as expected — they land outside /home/node.

To install anything that lives under /home/node, do it after the volume is mounted instead:

• Ask the agent — it can run the command inside its container with the exec tool.
• Extend init.sh — it's the entrypoint and runs on every boot after the volume is mounted, so its changes to /home/node stick and re-apply even to a fresh volume.

Connect the OpenClaw CLI

You can operate your deployed gateway from your own machine with the OpenClaw CLI; a local gateway is not required.

1. Install the matching version. Install the version the image pins (see the Dockerfile, or the version shown in the control UI) — a CLI that speaks a different gateway wire protocol is rejected at connect with protocol mismatch, and matching the pinned version is the reliable way to avoid that. Node 26 is recommended; Node 22.22.3+, 24.15+, or 25.9+ are supported, per the installation guide:

npm install -g openclaw@2026.8.2

2. Point the CLI at your gateway. Configure remote gateway mode:

openclaw config set gateway.mode remote
openclaw config set gateway.remote.url wss://your-gateway.example.com
openclaw config set gateway.remote.password '<gateway-password>'

Use your gateway's public wss:// URL and the credential it is configured with — for this template, the value you set in OPENCLAW_GATEWAY_PASSWORD.

Note: These examples use wss:// (TLS). If your gateway is reachable only over plaintext ws://, use a ws:// URL instead — and, since the gateway host is public, set the break-glass variable in the shell running the CLI before connecting:

export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1

Plaintext ws:// exposes your token and chat traffic to network interception. To use wss:// instead, enable SSL for your app in the Hyperlift manager.

3. Test the connection:

openclaw health
openclaw agent --agent main --message "Say hi"

health works right away. The first command that talks to the agent reports pairing required: device is not approved yet. The template's device-autopair plugin approves it within about five seconds — wait a moment and run it again. If it stays pending, approve it manually under Settings → Connections → Devices → Paired devices.

4. Approve scope upgrades when prompted. OpenClaw grants access per action, by least-privilege design — there is no way to pre-approve everything from the CLI. The first time you run a command that needs broader access — for example, messaging the agent:

openclaw agent --agent main --message "hello from the cli"

you will see scope upgrade pending approval. Approve it under Settings → Connections → Devices — the device-autopair plugin deliberately never auto-approves upgrades for an already-paired device, so this one is always a manual click. Routine use afterward does not prompt again unless an action requires a new scope.

Remote CLI limitations

The CLI talks to the gateway over its WebSocket API; it is not a shell inside the container. Use it to operate the running gateway: check health, tail logs, message the agent (agent --message …), manage cron jobs, approve devices.

Installation and setup commands — config, plugins, models, onboard, and similar — act on the machine the CLI runs on, not the remote gateway. They complete without error even with remote mode configured.

To change the deployment itself, use one of the methods in Editing the configuration — ask the agent, the control UI, /bash, or the git-sync branch. For low-level access, openclaw gateway call invokes gateway RPC methods directly.

Reference: Installation · Remote gateway · Devices & pairing

Git sync (optional)

The agent's workspace already persists on the deployment's volume across restarts and redeploys. Git sync is optional: it mirrors the workspace to a dedicated workspace-sync branch of your GitHub repository.

Set up:

1. Create a fine-grained GitHub PAT (Settings → Developer settings → Personal access tokens → Fine-grained), scoped to the single repository this app deploys from, with Contents: read and write.
2. Set WORKSPACE_GIT_URL (your template repository's HTTPS URL, e.g. https://github.com/you/repo.git) and WORKSPACE_GIT_TOKEN (the PAT) in your Hyperlift environment — saving them restarts the app automatically, and sync is set up on the way back up.

On first sync, the agent's current workspace becomes the first commit on a new workspace-sync branch — a standalone branch that holds only the workspace files, kept separate from your app's code.

What syncs: the agent's workspace/ directory, its openclaw.json configuration, and skills/. Runtime state — credentials, sessions, and scheduled jobs — stays local to the container and is never committed.

Never put secrets in openclaw.json. With sync on, anything in that file is pushed to your repository in plaintext — keep API keys and tokens in your Hyperlift environment variables instead. See Security.

Edit the workspace from your machine:

git clone <your-repo-url>
cd <repo>
git checkout workspace-sync
# edit files under workspace/ (e.g. workspace/IDENTITY.md)
git add workspace/ && git commit -m "tweak agent" && git push

Then tell the agent "pull from git" and it picks up your changes. Ask it to "sync to git" to push its own changes on demand.

Good to know:

• Two-way and mostly automatic. The agent syncs at natural points and on request ("sync to git", "pull from git") — each sync pulls your edits and pushes the agent's.
• Portable. The branch is the workspace's durable, off-cluster copy: point a new app at the same repo and it comes up with the agent's memory, personality, and config intact.
• Conflict-safe. If changes can't merge cleanly, the agent keeps the remote and saves its divergent work on a backup/<timestamp> branch — nothing is overwritten.

Security

The gateway and its web chat are served on a public URL, so treat the deployment as internet-facing:

• Set a strong, unique gateway password and rotate it regularly. It is the only thing between the public internet and your agent. OpenClaw also asks for a one-time approval of every new browser. Approving normally takes a shell on the gateway or an already approved browser, which a fresh Hyperlift deployment does not have, so the template's device-autopair plugin approves those requests for you. Node enrollments stay manual under Settings → Connections → Devices. You can turn the plugin off by setting plugins.entries.device-autopair.enabled to false; new browsers then need approval from a browser that is already paired.
• Keep secrets in environment variables, not in openclaw.json. OpenClaw reads keys such as OPENAI_API_KEY straight from the environment, and can substitute env values into the config where you do need to reference one — so a secret rarely has to live in the file at all, which also keeps it out of git sync.
• Disable what you don't use. The template turns on the unrestricted /bash command in the web chat for provider onboarding (see Configure your model provider). Once done, set commands.bash to false in the config so a compromised UI cannot run commands in the container. Questions and diagnosis still work through /openclaw; repairs need /bash.

Troubleshooting

• A provider or its models don't appear after you set them up. Confirm the plugin is enabled and the key is set (see Configure your model provider), then restart the app from the Hyperlift manager. If it still misbehaves, run /bash openclaw doctor --fix from the web chat to repair common configuration problems. (/openclaw doctor gives a read-only diagnosis, but repairs refuse to run from the chat — if you've turned /bash off, re-enable it first.)
• Git sync is not working. Check the container logs. The most common causes are an expired PAT, an SSH-form URL instead of HTTPS, or a PAT missing Contents: read and write. If the remote cannot be reached, the container falls back to local-only mode and keeps running.
• The CLI reports protocol mismatch. The CLI and gateway versions differ — install the version this template pins (see Connect the OpenClaw CLI).
• The CLI reports scope upgrade pending. Approve the device in the control UI under Settings → Connections → Devices. (A plain pairing required clears itself within a few seconds via device-autopair — just retry.)
• A plugin/skill/config change made via the CLI doesn't show up in the deployment. Install- and config-type commands act on the machine running the CLI, not the remote gateway. See Remote CLI limitations.
• openclaw dashboard or openclaw gateway status reports the gateway is not running. Both check for a gateway on the local machine. Use openclaw health to check the deployment.
• Something installed in the Dockerfile is missing at runtime. If the build wrote it under /home/node (plugins, skills, caches), the persistent volume mounts over it — install it after boot instead. See Persistent storage.
• The app restarts or runs out of memory (OOMKilled). This template disables the Codex plugin (plugins.entries.codex.enabled: false) and pins OpenAI models to OpenClaw's lighter built-in runtime (models.providers.openai.agentRuntime.id: "openclaw" in seed/openclaw.default.json). Without the pin, OpenAI models on the official API route to OpenAI's Codex runtime, which runs the agent in a separate app-server and spawns a full helper process per tool call — enough to exhaust a medium instance. And with the plugin disabled but the pin missing, OpenAI models fail outright with runtime "codex" is unavailable, so keep the two settings together. Non-OpenAI models are unaffected. Re-enable codex (and remove the pin) only if you want its agentic/code-execution features and have given the app more memory.

License

This template is released under the MIT License.