KrustyPlanet/obm
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

add documentation trio: README (casual), DETAILS (technical), LLMs (agent reference)
Some checks failed
CI / Test (pull_request) Failing after 56s
Details
CI / Build (pull_request) Has been skipped
Details
CI / Build-1 (pull_request) Has been skipped
Details
CI / Build-2 (pull_request) Has been skipped
Details
CI / Build-3 (pull_request) Has been skipped
Details
CI / Build-4 (pull_request) Has been skipped
Details

Browse source
This commit is contained in:
MermaidMan 2026-05-22 17:17:51 +00:00
parent 21f2bd3a9d
commit bf9499bac0
3 changed files with 821 additions and 131 deletions
Download patch file Download diff file Expand all files Collapse all files

262
README.md
View file

@ -1,167 +1,167 @@
# obm - OpenBoatMobile Infrastructure CLI
# obm 🚢
A CLI tool for deploying AI agents on cloud infrastructure with Terraform.
**Deploy your own AI agent to the cloud in about five minutes.**
## Installation
No YAML file editing. No guessing if your API keys work. No 94-line config templates.
Just answer a few questions and your agent is live.
### Quick Install (Linux/macOS)
---
## What is this?
`obm` is a command-line tool that walks you through setting up an AI agent on cloud infrastructure. It asks you things like "which cloud provider?" and "which AI model?" — then validates your answers on the spot, writes the config, and hands it off to Terraform to build everything.
It supports two agent frameworks:
- **Hermes Agent** (by Nous Research) — a Python-based agent with Discord chat, voice, web search, and a ton of integrations. Think of it as a personal AI assistant you can talk to.
- **OpenClaw** — a Node.js-based agent with a simpler setup. Good if you want something lighter.
Both run on either **Hetzner Cloud** (cheap, EU-based) or **DigitalOcean** (more regions).
---
## Quick start
### Install
**Mac or Linux (one command):**
```bash
curl -fsSL https://raw.githubusercontent.com/openboatmobile/obm/main/scripts/install.sh | sh
```
Install a specific version:
**Or download a binary** from the [releases page](https://github.com/openboatmobile/obm/releases/latest) and put it somewhere on your PATH.
**Or build from source** (requires Go 1.22+):
```bash
curl -fsSL https://raw.githubusercontent.com/openboatmobile/obm/main/scripts/install.sh | sh -s -- v1.2.3
git clone https://github.com/openboatmobile/obm.git
cd obm
make build
```
### Manual Install
Download the latest release for your platform from [GitHub Releases](https://github.com/openboatmobile/obm/releases/latest):
| Platform | Architecture | Download |
|----------|-------------|----------|
| Linux | x86_64 (amd64) | `obm-linux-amd64.tar.gz` |
| Linux | ARM64 | `obm-linux-arm64.tar.gz` |
| macOS | Apple Silicon (arm64) | `obm-darwin-arm64.tar.gz` |
| Windows | x86_64 (amd64) | `obm-windows-amd64.zip` |
| Windows | ARM64 | `obm-windows-arm64.zip` |
**Linux/macOS:**
```bash
# Download and extract
curl -sL https://github.com/openboatmobile/obm/releases/latest/download/obm-linux-amd64.tar.gz | tar xz
# Or for ARM64:
# curl -sL https://github.com/openboatmobile/obm/releases/latest/download/obm-linux-arm64.tar.gz | tar xz
chmod +x obm
sudo mv obm /usr/local/bin/
```
**Windows (PowerShell):**
```powershell
# Download and extract
Invoke-WebRequest -Uri https://github.com/openboatmobile/obm/releases/latest/download/obm-windows-amd64.zip -OutFile obm.zip
Expand-Archive obm.zip
# Add to PATH as needed
```
### From Source
### Deploy your agent
```bash
go build -o obm ./cmd/obm
obm deploy
```
## Usage
That's it. You'll get an interactive walkthrough that looks like this:
### Interactive Mode (Default)
```
🚢 OpenBoatmobile — Deploy your AI agent
Run the interactive wizard to configure your deployment:
Step 1: Agent Framework
[1] Hermes Agent (Nous Research) — Python-based, highly configurable
[2] OpenClaw — Node.js-based, simpler setup
```bash
./obm deploy
Step 2: Cloud Provider
[1] Hetzner Cloud — from €4.49/mo (recommended, ~70% cheaper)
[2] DigitalOcean — from $6/mo (wider region availability)
Step 3: Provider API Token
Get yours at: https://console.hetzner.cloud/ → Security → API Tokens
Token: ********
✓ Token validated
...
```
The wizard will guide you through:
1. Agent framework selection (Hermes or OpenClaw)
2. Cloud provider (Hetzner or DigitalOcean)
3. Server configuration
4. Inference provider (Venice, OpenRouter, OpenAI, Anthropic, or Custom)
5. Optional: Tailscale VPN, Discord integration
At the end, you'll see a summary with cost estimate and get asked to confirm. Say yes, and `obm` writes your config and kicks off Terraform.
### Non-Interactive Mode (CI/CD)
### Other commands
For automated deployments, use a YAML configuration file:
```bash
./obm deploy --config deploy.yaml
```
See `deploy.yaml.example` for a complete configuration reference.
## Commands
| Command | Description |
| Command | What it does |
|---------|-------------|
| `deploy` | Deploy an AI agent (interactive or --config for CI/CD) |
| `validate` | Check configuration and API credentials |
| `status` | Show current infrastructure state |
| `destroy` | Tear down provisioned infrastructure |
| `version` | Print version |
| `help` | Show help message |
| `obm deploy` | Interactive walkthrough to set up a new agent |
| `obm validate` | Checks your existing config and API keys |
| `obm status` | Shows the state of your current deployment |
| `obm destroy` | Tears down your infrastructure (asks first, don't worry) |
| `obm version` | Prints the version |
## Configuration File Format
### Non-interactive mode (for automation)
The YAML configuration file supports the following structure:
```yaml
# Required: Agent framework
framework: hermes # or openclaw
# Required: Cloud provider
provider:
name: hetzner # or digitalocean
token: "your-api-token"
ssh:
names: ["my-ssh-key"] # Hetzner
# fingerprints: ["aa:bb:cc:dd"] # DigitalOcean
# Server configuration
server:
name: "my-agent"
location: "ash" # Hetzner: ash, fsn1, nbg1, hel1
type: "cpx21"
# Required: Inference provider
inference:
provider: venice # venice, openrouter, openai, anthropic, custom
api_key: "your-api-key"
primary_model: "zai-org-glm-5"
# Optional: Tailscale VPN
tailscale:
enabled: true
auth_key: "tskey-auth-..."
tailnet: "mytailnet"
# Optional: Discord integration
discord:
enabled: true
bot_token: ""
server_id: ""
```
## Example Workflows
### Local Development
If you're running this in CI/CD or just don't want the prompts:
```bash
# Interactive setup
./obm deploy
# Validate your .env file
./obm validate --env-file .env
obm deploy --config deploy.yaml
```
### CI/CD Pipeline
See [`deploy.yaml.example`](deploy.yaml.example) for the full config file format.
```bash
# Create deploy.yaml from your secrets manager
# Then run non-interactive deployment
./obm deploy --config deploy.yaml
```
---
### GitOps Setup
## What you'll need
1. Store `deploy.yaml` in your repository (use template with placeholders)
2. Use a secrets manager for sensitive values
3. In CI:
```bash
envsubst < deploy.yaml.template > deploy.yaml
./obm deploy --config deploy.yaml
```
Before running `obm deploy`, have these ready:
1. **A cloud provider account** — [Hetzner Cloud](https://console.hetzner.cloud/) or [DigitalOcean](https://cloud.digitalocean.com/). Hetzner is cheaper; DigitalOcean has more data center locations.
2. **An API token** from your cloud provider. You can generate one in their dashboard.
3. **An AI model API key** — Venice AI, OpenRouter, OpenAI, or Anthropic. This is the "brain" your agent will use.
4. **An SSH public key** uploaded to your cloud provider (so you can log into your server later).
Optional but recommended:
- **Tailscale** account for VPN access to your server
- **Discord bot token** if you want your agent to chat on Discord
---
## How much does it cost?
The server cost depends on your cloud provider and server size. `obm` shows you the estimated monthly cost before you commit.
**Rough starting points:**
| Provider | Smallest option | Good for |
|----------|----------------|----------|
| Hetzner | €4.49/mo (2 vCPU, 4 GB RAM) | Most agents |
| DigitalOcean | $6/mo (1 vCPU, 1 GB RAM) | Light use |
The AI model API costs are separate and depend on your usage.
---
## What happens under the hood?
`obm` generates a `.env` file that [Terraform](https://terraform.io) reads to provision your server, install the agent software, and configure everything. You don't need to know Terraform — `obm` handles it.
The Terraform configs live in the [openboatmobile-ai](https://github.com/openboatmobile/openboatmobile-ai) repo. `obm` is the friendly CLI wrapper around them.
---
## Project status
`obm` is actively developed and functional for the core deploy workflow. Here's what works and what's coming:
**Working now:**
- Interactive deploy walkthrough (8 steps)
- API key validation for cloud providers and inference providers
- SSH key listing from Hetzner
- `.env` file generation
- Config validation (`obm validate`)
- Infrastructure teardown (`obm destroy`)
- Non-interactive mode with YAML config
- Cross-compiled binaries (Linux, macOS, Windows)
- `curl | sh` installer
**Coming soon:**
- `obm status` — SSH health checks on your deployment
- DigitalOcean provider validation
- Cost estimation display
- Resumable deploy (pick up where you left off)
---
## For developers
Building, testing, and contributing — see [DETAILS.md](DETAILS.md) for the full technical reference and [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guide.
## For AI agents
If you're an AI agent reading this to learn about the project, check out [LLMs.md](LLMs.md) — it's written specifically for you.
---
## License
MIT
MIT