0. TL;DR

I took three months of my own AI-agent session logs (352 sessions, 2.8 GB), curated them into 2,580 (error -> recovery) training pairs, fine-tuned a small open-weights model with a LoRA adapter (74 MB, 0.1% of parameters), and ended up with a local specialist that recognizes my environment’’s failure modes and proposes my fixes — for under $50 of GPU time. It works. It also fails in instructive ways. Both are documented below with numbers.

1. The data: raw traces are not training data

Source. 352 session logs (rollout JSONL) from my daily agent-driven work: cloud API operations, database work, spreadsheets, git. Every record is a timestamped JSON blob: user messages, assistant reasoning, tool calls, tool outputs.

Curation. Raw logs are ore, not metal. The curation pipeline (~100 lines of Python):

1. Find error moments — regex over tool outputs (permission denied, not found, timeout, non-zero exit codes): 4,135 candidates across 104 sessions (30% of sessions had errors).
2. Verify recovery — keep a moment only if the next tool call produced clean output. No verified recovery, no training pair. This is the step that keeps flailing out of the dataset.
3. Compress context — task (last user message), recent activity (few calls), the error text; each field truncated.
4. Scrub — instance ids, keys, tokens, IPs masked (91k lines matched secret patterns).
5. Dedupe — hash on (error, action); 500 identical recoveries count once.

Result: 2,580 pairs, plus 3,186 more from shell-history logs (adjacent-command typo/flag fixes, with a destructive-escalation guard: never teach ls -> rm -rf).

Per-class distribution (this matters later):

2. The method: a small base + a small tensor

• Base: ~1.5B-parameter open-weights instruct model. Small on purpose — the hypothesis was that this task needs reflexes, not breadth.
• LoRA: rank 16, alpha 32, on all attention + FFN projections. Trainable params: 18.5M of 1,562M (1.18%). The base stays frozen; only the fresh A/B tensors learn.
• Merge after training: W_new = W + alpha * B * A per layer — one matrix multiply and the adapter becomes ordinary weights.
• Stack: torch / transformers / peft / trl (SFTTrainer, chat-format messages, loss on assistant tokens only), single A10 GPU.

Training: 3 epochs over 2,580 pairs, batch 4, 56 minutes wall time. Loss 2.33 -> 0.35; mean token accuracy ~90%.

Cost: well under $50 of GPU time. The model weights are free. Total cost of the custom model: $50.

3. Packaging gotchas (the part blogs skip)

• **TRL 1.9.x defaults ****loss_type="chunked_nll"**, which monkeypatches the model forward and crashes against PEFT adapters. Fix: loss_type="nll".
• Triton needs Python headers on a fresh node: apt-get install python3.10-dev, or kernel compiles fail cryptically.
• Ollama’’s internal safetensors->GGUF converter hung on my fp32 merge (every request spun forever — even “hi”). The official llama.cpp convert_hf_to_gguf.py produced a working GGUF on the first try. Lesson: convert yourself.
• Bake the system prompt into the Modelfile (SYSTEM """..."""). Without it, the trained format discipline never triggers in a plain ollama run session — the model reverts to generic chat.

4. Evaluation: what it learned, measured by interrogation

Identity and format. Asked “who are you”, it answered “I am an agent-loop controller” — the persona from the training system prompt, learned from data alone. Given error states in the trained format, it emits the controller JSON: {"tool": "exec_command", "args": ...}.

The good. A novel error (“deployment not found”, never in training) produced a correct recovery reflex — check existence first — in my own shell idiom, down to 2>/dev/null || true. That is not in any textbook; it is from my logs.

The bad. A git non-fast-forward error produced, without the controller context, a confident recommendation of git push -f origin master — the classic destructive mistake. Two lessons: (1) base-model “knowledge” leaks through when the trained context is absent; (2) the baked system prompt now carries an explicit never-recommend-destructive-actions rule. Guardrails live in prompts and harnesses, not hopes.

The map. Performance tracks the class distribution almost exactly: strong on ssh/auth and cloud/region errors (150+ pairs each), weak on git (52 pairs), absent on shell-parse (2 pairs). The apprenticeship is literal: no examples, no skill.

5. What I actually concluded

1. The loop is learnable, cheaply. CLI -> error -> recovery -> resolution, for a specific environment, fits in 74 MB. The $50/dinner comparison is real.
2. Curation > volume. 2,580 verified-recovery pairs beat 2.8 GB of raw logs. The extractor rules are where the domain knowledge lives.
3. The model has no opinion — and that is the point. It proposes my fixes, in my format, and otherwise stays out of the way. The poetry belongs to other models.
4. The failure modes are data problems, not model problems. Git and shell-parse are weak because my logs are thin there. The fix is a simulator for those classes, not a bigger model.

6. Reproduce it

The full pipeline (extractors, trainer, merge, GGUF, Modelfile, node runbook) is a folder of small scripts; the whole thing reruns end-to-end in about an hour of GPU time plus curation. If you have three months of agent logs, you already own the hard part.

Next in the series: the per-class evaluation harness — measuring which error classes the specialist actually owns, and the round-two data build (paraphrase robustness, guardrails, and the error-class simulator).

It turns out this is not a bug in the model or the agent. It’s a feature of the Grok Build TUI (the interactive terminal UI you’re using right now).

The Two Ways to Enter Multiline Text

There are two distinct concepts that both involve “multiline”:

1. Multiline input mode (/multiline or Ctrl+M when prompt is focused)
2. Writing actual multiline comments or code blocks in your prompts/responses

1. Toggling Multiline Input Mode

By default, when the prompt is focused:

• Enter = send the message
• You cannot easily type newlines

Running /multiline (or pressing Ctrl+M) toggles the mode:

• Enter now inserts a newline
• Shift+Enter (or Alt+Enter) sends the message

This is exactly what the /multiline slash command (and the recent MRU entry in ~/.grok/slash-mru.json) does. It’s documented in the user guide under keyboard shortcuts and slash commands.

The TUI even has special logic so that mid-turn, an empty prompt + bare Enter still acts as “send now” for queued follow-ups.

2. Multiline Comments in Code/Prompts

Once in the correct input mode (or using Shift+Enter in normal mode), you can write multiline comments, code blocks, YAML, etc. The highlight.js setup in this blog already supports comments in several languages (TSQL, PowerShell, CSS, HTML).

The “show stopper” feeling usually comes from one of two places:

• Not knowing Ctrl+M / /multiline exists
• Terminal-specific keyboard protocol issues (WezTerm, tmux, Zellij, Windows Terminal) that prevent Shift+Enter or Ctrl+Enter from registering properly

Quick Fixes for Common Terminal Issues

See the full user guide (~/.grok/docs/user-guide/21-terminal-support.md or run /terminal-setup in the TUI) for your specific terminal. Common ones:

• WezTerm: Add enable_kitty_keyboard = true to your config
• Zellij: Use the “Unlock-First (non-colliding)” preset
• tmux: Enable extended-keys on
• Windows Terminal: Use Alt+V for images; rebind conflicting Ctrl+L if using VS Code family

Why This Matters for Agents

The recent Kimi K3 posts highlighted how much context is wasted on “explain the project to me.” The new GROK.md in this repo (created during this resume session) front-loads the exact conventions so agents waste fewer tokens and fewer turns on tool flailing.

The TUI’s /multiline (or Ctrl+M), keyboard shortcuts (Ctrl+;, Ctrl+P for palette), skills system, GROK.md context file, and permission model are all designed to make tight, prescriptive workflows efficient.

Note on persistence: Multiline mode is per-session (toggled with /multiline or Ctrl+M). There is currently no default_multiline = true setting in ~/.grok/config.toml or pager.toml. Run it once at the start of a session or add it to your muscle memory.

Multiline input is not a limitation—it’s a deliberate design choice that, once you know the chord (Ctrl+M then Shift+Enter to send), becomes muscle memory.

No longer a showstopper.

(Yes, this entire post — including the updates above — was written in multiline mode.)

None of these are dealbreakers. But if I had read them before I started, I would have saved myself a couple of hours and a chunk of context window I did not need to burn.

Why WSL at all

My daily driver is a Windows 11 laptop, but every coding-agent tool I like assumes a Unix shell. Rather than fight that, I run everything inside WSL2 with an Ubuntu distribution. The Kimi Code CLI and the Claude Code-style terminal flow both behave like they are on Linux, because from their point of view they are.

If you do not already have WSL set up, from an elevated PowerShell:

wsl --install -d Ubuntu

Then reboot, let Ubuntu finish first-run setup, and do the rest inside the WSL shell, not PowerShell. That distinction matters more than it sounds like, because a lot of the confusion later came from tools and keys that care which environment they were created in.

Inside WSL, the install itself is the easy part:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
kimi --version

And pointing a Claude Code-style flow at Kimi:

export ANTHROPIC_BASE_URL=https://api.kimi.com/coding/
export ANTHROPIC_API_KEY="your-kimi-code-api-key"
export ANTHROPIC_MODEL="k3[1m]"

That part took ten minutes. The rest of this post is everything that was not ten minutes.

Challenge (a): the API key only works with the path you got it for

This was the first wall I hit, and it is the one I most want to warn people about.

Kimi has three different paths, and they are not interchangeable:

• Kimi Code (Anthropic-compatible) — https://api.kimi.com/coding/
• Kimi Code (OpenAI-compatible) — https://api.kimi.com/coding/v1
• Kimi Open Platform — https://api.moonshot.cn/v1

The trap is that a key minted for one path does not authenticate against another. I generated a key, wired it in, and got authentication errors that looked like the key was bad. It was not bad. It was a perfectly valid key — for a different door.

The mental model that finally worked for me: the key is scoped to the product, not to “Kimi” in general. If you are doing the Claude Code-style integration, you need a Kimi Code key used against the Kimi Code base URL, and you have to keep the Anthropic-compatible vs OpenAI-compatible endpoints straight on top of that. Match the key, the base URL, and the API shape as a single unit. If any one of the three is from a different path, you get an error that misleadingly looks like a credentials problem.

Do the check early with /status and confirm the Base URL really is the coding endpoint before you go debugging anything else.

Challenge (b): the TUI sprays text while it thinks, and there is no silence key

Once it authenticates, you meet the interface. The Kimi TUI is busy. While the model is thinking, it streams a running commentary — reasoning, tool deliberation, partial plans — straight into the terminal, continuously.

I understand the intent. Visible thinking is reassuring the first time. By the tenth prompt it is noise. And the part that genuinely annoyed me: there is no silence key. No toggle I could find to say “think quietly, show me the result.” You cannot easily mute the stream, so long tasks scroll pages of thinking that you then have to scroll back through to find the actual answer or the actual diff.

On a small screen, this is worse. My WSL terminal window is not huge, and the thinking output pushed the meaningful output — the file it changed, the command it wanted to run — off the top before I could read it. I ended up leaning on my terminal’s own scrollback and search rather than anything the TUI offered.

If you are used to a calmer agent UI, budget some patience for this one.

Challenge (c): 12% of a 1M context window just to explain how the blog works

Here is the one that actually cost me money.

This blog is a plain Jekyll site. Posts live in _posts, the filename encodes the date and slug, and the front matter is three lines. That is the entire mental model. But getting the agent to reliably operate on it — find where posts live, match the existing tone, use the right filename format, not invent config that is not there — took a lot of back-and-forth.

By the time it genuinely understood the repo, I had burned roughly 12% of a 1,000,000-token context window. That is ~120k tokens spent on orientation, before a single useful line of the post was written.

Some of that is on me. In hindsight the fix is to front-load the context instead of letting the model discover it conversationally:

• Keep a short CLAUDE.md / project note describing the repo layout and the post format.
• Point the agent at one existing post as a template up front.
• State the filename convention explicitly rather than making it infer one.

But it is worth saying plainly: a large context window is not free, and “let the agent figure out the project” is a surprisingly expensive way to start. The 1M window lulls you into being lazy about scoping, and then you pay for it.

Challenge (d): it struggles to pick the right tool for the task

The other big time sink was watching it hunt for the right tool. Faced with a simple job — read a file, list a directory, make an edit — it would sometimes reach for the wrong approach first: shelling out where a direct file read would do, or exploring broadly when the target was already known.

Individually these detours are small. Cumulatively they add up, both in wall-clock time and in context consumed (see challenge c — a lot of that 12% was tool flailing). It made the whole effort feel slower and less deterministic than I wanted. The task was never in doubt; the route to it was.

What helped was being more prescriptive. Instead of “add a new blog post,” something closer to “create a file at _posts/YYYY-MM-DD-slug.md with this front matter, matching the style of this existing post” gave it far less room to wander. The less I left to tool discovery, the better it went.

Challenge (e): I am genuinely not sure it is cheaper

The pitch for going to Kimi K3 was partly cost. And here is my honest verdict after doing real work with it: I am not sure it actually saved me anything.

The per-token price may well be lower. But cost is not just the sticker rate, it is rate times tokens times number of turns. And on this task:

• The chatty TUI and the tool flailing meant more turns.
• The orientation problem meant a large upfront token spend (that 12%).
• More turns and more tokens partly eat whatever the lower per-token rate saves you.

So the theoretical savings and the effective savings are not the same number. On a well-scoped task where I hand it tight context, I suspect Kimi K3 could come out genuinely cheaper. On this task — loosely scoped, exploratory, lots of back-and-forth — the efficiency losses clawed back a good part of the discount. I did not come away convinced I had saved money. I came away thinking the savings are real only if you work in a way that keeps token count down, which is exactly the way the tool does not naturally nudge you toward.

Would I do it again?

Yes, but differently. The install on Windows 11 via WSL is not the hard part — that genuinely is a ten-minute job. The hard part is everything around the model:

• Get the key/path/endpoint triad right the first time (challenge a).
• Make peace with, or scroll past, the noisy TUI (challenge b).
• Front-load project context so you are not paying to explain the obvious (challenge c).
• Be prescriptive about the task so it does not shop for tools (challenge d).
• Do not assume “cheaper per token” means “cheaper overall” (challenge e).

Kimi K3 with a 1M context window is a capable backend, and running it under WSL on Windows 11 works fine. But the experience rewards discipline and punishes hand-waving. Go in with tight scope, or go in expecting to pay for the slack.

None of these are dealbreakers. But if I had read them before I started, I would have saved myself a couple of hours and a chunk of context window I did not need to burn.

Why WSL at all

My daily driver is a Windows 11 laptop, but every coding-agent tool I like assumes a Unix shell. Rather than fight that, I run everything inside WSL2 with an Ubuntu distribution. The Kimi Code CLI and the Claude Code-style terminal flow both behave like they are on Linux, because from their point of view they are.

If you do not already have WSL set up, from an elevated PowerShell:

wsl --install -d Ubuntu

Then reboot, let Ubuntu finish first-run setup, and do the rest inside the WSL shell, not PowerShell. That distinction matters more than it sounds like, because a lot of the confusion later came from tools and keys that care which environment they were created in.

Inside WSL, the install itself is the easy part:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
kimi --version

And pointing a Claude Code-style flow at Kimi:

export ANTHROPIC_BASE_URL=https://api.kimi.com/coding/
export ANTHROPIC_API_KEY="your-kimi-code-api-key"
export ANTHROPIC_MODEL="k3[1m]"

That part took ten minutes. The rest of this post is everything that was not ten minutes.

Challenge (a): the API key only works with the path you got it for

This was the first wall I hit, and it is the one I most want to warn people about.

Kimi has three different paths, and they are not interchangeable:

• Kimi Code (Anthropic-compatible) — https://api.kimi.com/coding/
• Kimi Code (OpenAI-compatible) — https://api.kimi.com/coding/v1
• Kimi Open Platform — https://api.moonshot.cn/v1

The trap is that a key minted for one path does not authenticate against another. I generated a key, wired it in, and got authentication errors that looked like the key was bad. It was not bad. It was a perfectly valid key — for a different door.

The mental model that finally worked for me: the key is scoped to the product, not to “Kimi” in general. If you are doing the Claude Code-style integration, you need a Kimi Code key used against the Kimi Code base URL, and you have to keep the Anthropic-compatible vs OpenAI-compatible endpoints straight on top of that. Match the key, the base URL, and the API shape as a single unit. If any one of the three is from a different path, you get an error that misleadingly looks like a credentials problem.

Do the check early with /status and confirm the Base URL really is the coding endpoint before you go debugging anything else.

Challenge (b): the TUI sprays text while it thinks, and there is no silence key

Once it authenticates, you meet the interface. The Kimi TUI is busy. While the model is thinking, it streams a running commentary — reasoning, tool deliberation, partial plans — straight into the terminal, continuously.

I understand the intent. Visible thinking is reassuring the first time. By the tenth prompt it is noise. And the part that genuinely annoyed me: there is no silence key. No toggle I could find to say “think quietly, show me the result.” You cannot easily mute the stream, so long tasks scroll pages of thinking that you then have to scroll back through to find the actual answer or the actual diff.

On a small screen, this is worse. My WSL terminal window is not huge, and the thinking output pushed the meaningful output — the file it changed, the command it wanted to run — off the top before I could read it. I ended up leaning on my terminal’s own scrollback and search rather than anything the TUI offered.

If you are used to a calmer agent UI, budget some patience for this one.

Challenge (c): 12% of a 1M context window just to explain how the blog works

Here is the one that actually cost me money.

This blog is a plain Jekyll site. Posts live in _posts, the filename encodes the date and slug, and the front matter is three lines. That is the entire mental model. But getting the agent to reliably operate on it — find where posts live, match the existing tone, use the right filename format, not invent config that is not there — took a lot of back-and-forth.

By the time it genuinely understood the repo, I had burned roughly 12% of a 1,000,000-token context window. That is ~120k tokens spent on orientation, before a single useful line of the post was written.

Some of that is on me. In hindsight the fix is to front-load the context instead of letting the model discover it conversationally:

• Keep a short CLAUDE.md / project note describing the repo layout and the post format.
• Point the agent at one existing post as a template up front.
• State the filename convention explicitly rather than making it infer one.

But it is worth saying plainly: a large context window is not free, and “let the agent figure out the project” is a surprisingly expensive way to start. The 1M window lulls you into being lazy about scoping, and then you pay for it.

Challenge (d): it struggles to pick the right tool for the task

The other big time sink was watching it hunt for the right tool. Faced with a simple job — read a file, list a directory, make an edit — it would sometimes reach for the wrong approach first: shelling out where a direct file read would do, or exploring broadly when the target was already known.

Individually these detours are small. Cumulatively they add up, both in wall-clock time and in context consumed (see challenge c — a lot of that 12% was tool flailing). It made the whole effort feel slower and less deterministic than I wanted. The task was never in doubt; the route to it was.

What helped was being more prescriptive. Instead of “add a new blog post,” something closer to “create a file at _posts/YYYY-MM-DD-slug.md with this front matter, matching the style of this existing post” gave it far less room to wander. The less I left to tool discovery, the better it went.

Challenge (e): I am genuinely not sure it is cheaper

The pitch for going to Kimi K3 was partly cost. And here is my honest verdict after doing real work with it: I am not sure it actually saved me anything.

The per-token price may well be lower. But cost is not just the sticker rate, it is rate times tokens times number of turns. And on this task:

• The chatty TUI and the tool flailing meant more turns.
• The orientation problem meant a large upfront token spend (that 12%).
• More turns and more tokens partly eat whatever the lower per-token rate saves you.

So the theoretical savings and the effective savings are not the same number. On a well-scoped task where I hand it tight context, I suspect Kimi K3 could come out genuinely cheaper. On this task — loosely scoped, exploratory, lots of back-and-forth — the efficiency losses clawed back a good part of the discount. I did not come away convinced I had saved money. I came away thinking the savings are real only if you work in a way that keeps token count down, which is exactly the way the tool does not naturally nudge you toward.

Would I do it again?

Yes, but differently. The install on Windows 11 via WSL is not the hard part — that genuinely is a ten-minute job. The hard part is everything around the model:

• Get the key/path/endpoint triad right the first time (challenge a).
• Make peace with, or scroll past, the noisy TUI (challenge b).
• Front-load project context so you are not paying to explain the obvious (challenge c).
• Be prescriptive about the task so it does not shop for tools (challenge d).
• Do not assume “cheaper per token” means “cheaper overall” (challenge e).

Kimi K3 with a 1M context window is a capable backend, and running it under WSL on Windows 11 works fine. But the experience rewards discipline and punishes hand-waving. Go in with tight scope, or go in expecting to pay for the slack.

Codex, Claude, and most “single agent” tools are fantastic at orchestrating one capable agent. But when you need a network of specialized agents talking to each other, xAI gives you the knobs, the server-side orchestration, and the parallel execution capabilities that feel purpose-built for it.

Here are the pieces that stand out.

1. Native Multi-Agent Mode and Spawning

xAI (particularly through Grok Build and the underlying agent SDK) makes it trivial to spawn multiple agents in parallel or sequence.

The subagent system (spawn_subagent tool) lets you launch specialized agents with different roles, models, and capabilities (e.g. explore, plan, general-purpose). You can run them in isolation (using git worktrees so edits don’t collide) or share state.

Use case that just works: A daily “access token refresh” agent that runs in the background, checks expiration, refreshes credentials across services, and notifies other agents. Spawning this in parallel with your main workflow is clean and doesn’t block.

2. Plan Mode as the Orchestrator

One of my favorite features is Plan Mode (/plan or the dedicated plan agent).

It lets you declare high-level intent and have Grok break it down into a sequenced plan, then execute it — often by chaining multiple specialized agents.

Example:

grok --plan "First, have a researcher agent analyze the SDK docs. Then, have a coder agent implement the client. Finally, have a tester agent write integration tests."

This is more powerful than it sounds. The planner can:

• Decide the sequence
• Spawn the right subagents with the right context
• Use file-based handoffs or shell scripts for communication between agents

It’s the closest thing I’ve seen to reliable agent chaining without building your own orchestration layer.

3. Server-Side Orchestration and Smart Tool Selection

Unlike purely local tools, xAI does a lot of the heavy lifting server-side: tool selection, parallel execution, context routing, and even some of the reasoning about which agent should handle which part of the task.

This reduces the “tool flailing” I complained about in the Kimi posts. The system is better at picking the right tool (or the right subagent) the first time.

4. Cursor Integration

The integration with Cursor is excellent. Grok Build feels like a natural extension of the Cursor workflow — you get the full power of the TUI (skills, MCP servers, subagents, plan mode, background tasks) while staying inside an editor that already understands your codebase.

It’s not just “chat in the sidebar.” It’s a real multi-agent backend that Cursor can call into.

Final Thoughts

xAI doesn’t market itself loudly as an AI tooling company. It’s part of the SpaceX family — the brand is rockets, Starlink, and pushing the boundaries of physics and intelligence.

But quietly, the combination of xAI + Grok Build + Cursor is becoming one of the strongest setups for high-performance, multi-agent software engineering I’ve used.

It rewards people who want to build networks of agents rather than just prompting one really smart model. The primitives are there: parallel spawning, plan-then-execute chaining, server-side orchestration, clean subagent isolation, and tight editor integration.

If you’re doing serious systems work — infrastructure, complex integrations, or anything that benefits from specialized agents working together — xAI deserves more attention than it gets.

It’s not trying to be the loudest AI company. It’s trying to be one of the most effective.

As one very frustrated user put it while fighting with the TUI: “You are very good at difficult things, but suck at simple things.”

And on that metric, it’s winning.

The short version is this: OpenClaw is not just a chat bot with a pretty shell. It is a local-first gateway that owns messaging surfaces, tools, sessions, and automation. Once I started looking at it that way, the setup made much more sense.

What OpenClaw actually is

The upstream project is openclaw/openclaw, and the architecture is centered around a long-lived local Gateway. The Gateway exposes a WebSocket control plane, maintains channel connections, and routes events into agent sessions.

That architecture matters because the three integrations I set up do not all enter the system the same way:

• Telegram is a native messaging channel connected directly to the OpenClaw gateway.
• Discord is also a native channel, but it needs a Discord application, bot token, gateway intents, and then pairing or allowlist configuration inside OpenClaw.
• Gmail is different. It is not just “another chat channel”. In practice it becomes an event-driven integration using gog, Google OAuth, Gmail watch, Google Pub/Sub, and OpenClaw hooks.

That is why the setup feels long. You are really stitching together several trust boundaries:

1. Your model provider auth for the LLM itself.
2. Your local OpenClaw gateway runtime.
3. Google OAuth plus Pub/Sub for Gmail.
4. Bot credentials and access control for Telegram and Discord.

My setup assumptions

I did this on WSL2, which OpenClaw explicitly recommends for Windows users. The upstream docs currently recommend Node 24 or at least Node 22.16+.

At a minimum, I would have these pieces ready before starting:

• node and npm
• openclaw
• gcloud
• gog
• a model account or API key for the LLM provider I want OpenClaw to use
• a Telegram bot token from @BotFather
• a Discord bot token from the Discord Developer Portal

The recommended install path is:

npm install -g openclaw@latest
openclaw onboard --install-daemon

If I want to run it in the foreground while debugging:

openclaw gateway --port 18789 --verbose

The important mental model is that the gateway is the control plane. Once it is up, the channels and automations hang off of it.

Why Gmail is the hardest integration

Telegram and Discord are basically messaging front ends. Gmail is not.

For Gmail, I had to solve three things:

• OAuth access to the mailbox
• a way for Gmail to notify my local OpenClaw stack when new mail lands
• a safe handoff path from that notification into an OpenClaw agent session

OpenClaw’s docs handle this with Gmail Pub/Sub integration and the gog CLI.

Step 1: authorize gog for Google services

OpenClaw uses gog for Google Workspace access. The setup is:

gog auth credentials /path/to/client_secret.json
gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets
gog auth list

That gives gog the OAuth credentials it needs to access Gmail and related Google APIs.

Step 2: enable Gmail API and Pub/Sub

The OpenClaw docs use Google Cloud Pub/Sub as the event path for Gmail watch notifications:

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

Then create a topic and grant Gmail permission to publish into it:

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

Step 3: start the Gmail watch

The lower-level manual path is:

gog gmail watch start \
  --account you@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

The OpenClaw-friendly path is simpler:

openclaw webhooks gmail setup --account you@gmail.com

That command writes hooks.gmail configuration, enables the Gmail preset, and prepares the push endpoint that the gateway will use.

Step 4: let the gateway own the watcher

This is the part that made the architecture click for me. Once hooks.enabled=true and hooks.gmail.account is configured, the gateway starts gog gmail watch serve on boot and auto-renews the watch.

So the runtime flow becomes:

1. Gmail sees a mailbox event.
2. Gmail publishes the event to the Pub/Sub topic.
3. gog receives and normalizes that watch event.
4. OpenClaw hooks ingest it.
5. The gateway routes the event into an agent session.

That is a very different pattern from a bot reading chat messages, and it explains why Gmail setup feels more like building an automation pipeline than enabling a simple inbox plugin.

Telegram integration

Telegram was much more straightforward.

Step 1: create a bot in BotFather

In Telegram, I created a bot with @BotFather, ran /newbot, and saved the token.

Step 2: configure the channel in OpenClaw

OpenClaw’s Telegram configuration can be as simple as:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

Telegram does not use a separate openclaw channels login telegram flow. I just configure the token and start the gateway.

Step 3: approve the first DM

With dmPolicy: "pairing", the first DM from an unknown sender gets a code instead of being processed immediately.

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

That pairing step is one of the better design choices in OpenClaw. It keeps my personal assistant from turning into a public endpoint just because someone discovers the bot username.

Step 4: optional group behavior

If I want the bot in a group, I can add the bot to the group and then decide whether the group needs explicit mention or always-on behavior. Telegram also has its own privacy-mode behavior, so group visibility depends partly on BotFather settings and partly on OpenClaw config.

For a private group, I would usually stay restrictive first and then loosen it only if I really want ambient participation.

Discord integration

Discord was somewhere in between Telegram and Gmail. It is not as operationally heavy as Gmail, but it is definitely more involved than Telegram because Discord wants a properly configured application and bot.

Step 1: create the application and bot

In the Discord Developer Portal, I created a new application, added a bot, and copied the bot token.

The critical part is enabling the right gateway intents:

• Message Content Intent is required.
• Server Members Intent is recommended.
• Presence Intent is optional.

Step 2: invite the bot with usable permissions

From the OAuth2 URL Generator, I enabled:

• bot
• applications.commands

And I made sure the bot had at least:

• View Channels
• Send Messages
• Read Message History
• Embed Links
• Attach Files

If I wanted thread-heavy usage, I would also enable Send Messages in Threads.

Step 3: configure the token in OpenClaw

I prefer not to store bot tokens inline, so an environment-backed config is cleaner:

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

{
  channels: {
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
    },
  },
}

Then I can start the gateway and pair from Discord DM.

Step 4: approve the first DM pairing

Once the gateway is running, I DM the bot in Discord and approve the pairing code:

openclaw pairing list discord
openclaw pairing approve discord <CODE>

At that point Discord DMs behave like a controlled front end into my assistant.

Step 5: make a private server usable

For a private guild, I can explicitly allow my server and user ID:

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,
          users: ["YOUR_USER_ID"],
        },
      },
    },
  },
}

That is a good default because it keeps the bot scoped to a server I control instead of wandering across whatever guilds it happens to be invited into.

The integration pattern that finally made sense to me

Once I had all three running, the OpenClaw model became much clearer:

• Telegram and Discord are conversational ingress channels.
• Gmail is an automation ingress path.
• The Gateway is the stable center of the system.

That is the part I missed the first time around. I originally thought of OpenClaw as “an AI that can check my Gmail”. Technically, it is closer to a personal agent gateway with multiple inbound surfaces and a local execution/control plane.

That explains the setup complexity, but it also explains the power. Once the integrations are in place, I can ask questions across those surfaces in a way that a conventional email client or single-channel bot does not really support.

For example, I can use Gmail as the data source, then talk to the assistant through Telegram or Discord, and let the same gateway manage the session, tooling, and response path.

Security notes that matter

This stack touches real personal communications, so I would not run it casually without guardrails.

The OpenClaw docs are pretty explicit about a few things that I agree with:

• keep DM policy on pairing or explicit allowlists
• keep Gmail hooks behind loopback, tailnet, or a trusted reverse proxy
• use a dedicated hook token instead of reusing the gateway auth token
• keep the bot in private Telegram groups or private Discord servers unless there is a real reason not to

The right default mindset is that inbound messages are untrusted input.

What I would tell someone before they try this

If someone wants to integrate OpenClaw with Gmail, Telegram, and Discord, this is what I would tell them up front:

• Telegram is the easiest. Get a bot token, start the gateway, approve pairing.
• Discord is manageable, but you need to be careful with intents, permissions, and allowlists.
• Gmail is the most technical because it is really a Google OAuth plus Pub/Sub plus webhook pipeline.
• WSL2 is a good place to do this on Windows because that is the path OpenClaw itself recommends.
• The local gateway is the whole point. If that architectural model does not make sense to you yet, the rest of the setup will feel random and frustrating.

Closing thought

What impressed me most about OpenClaw was not that it could read my email. Plenty of tools can do that. What impressed me was that it gave me a way to unify personal messaging channels, automation hooks, and agent execution around a local gateway that I control.

That is also why the setup is not trivial. The project is doing real systems integration work, not just wrapping an LLM in a chat window.

In practice, I usually bucket the common OpenShift options like this:

• OVN-Kubernetes default network for the standard pod network every workload gets
• OVN-Kubernetes secondary networks
  • layer2 when you want an isolated L2 domain for east-west traffic
  • localnet when you want that L2 domain to extend to a physical network
• macvlan when a pod needs a MAC on the external segment and you are comfortable with the macvlan communication model
• bridge when you want a pod attached through a Linux bridge-based secondary network
• SR-IOV when you need direct VF assignment, low overhead, and often VLAN-backed segmentation

For this post, I am focusing on OVN-Kubernetes localnet, because it gives a clean path to attach selected pods to an external network without changing the primary pod network model for the cluster.

The key OpenShift-specific piece in this workflow is the NodeNetworkConfigurationPolicy (NNCP). The NNCP is what programs the worker node networking so OVN-Kubernetes knows which host bridge should carry the localnet traffic.

Where localnet fits

localnet is an OVN-Kubernetes secondary network topology. It is useful when a pod needs:

• access to an existing physical subnet
• access to an external gateway on that subnet
• a second interface in addition to the default pod interface

Conceptually, the flow is:

1. Create a NodeNetworkConfigurationPolicy (NNCP) to define the host-side bridge mapping on the worker nodes.
2. Create a NetworkAttachmentDefinition that declares a localnet topology.
3. Attach a pod to that NAD with a Multus network annotation.
4. Exec into the pod and validate that the secondary interface and connectivity behave as expected.

Prerequisites

Before applying manifests, make sure the following are true:

• The cluster is using OVN-Kubernetes.
• The Kubernetes NMState Operator is installed.
• Multus secondary networks are available.
• The worker nodes can reach the target underlay network through the bridge you map.
• If the physical network is VLAN-tagged, the switch ports connected to the workers allow that VLAN.

Step 1: Create the namespace

oc create namespace test-net

Step 2: Create the NNCP bridge mapping

Use vlan200-nncp-ovn-localnet.yaml as the NodeNetworkConfigurationPolicy for the localnet bridge mapping.

Apply it:

oc apply -f assets/manifests/localnet/vlan200-nncp-ovn-localnet.yaml
oc get nncp br-ex-localnet

What this NNCP does:

• creates an OVN bridge mapping named vlan200-ovn-localnet
• maps that logical localnet name to br-ex
• makes br-ex the worker-side bridge used for the secondary network

The most important relationship is this one:

localnet: vlan200-ovn-localnet

That value must match the physicalNetworkName used later in the NetworkAttachmentDefinition.

If the NNCP is missing, the NAD alone is not enough. The pod might get the secondary attachment definition, but there will be no correct host-side mapping to the external network.

Optional: mapping a dedicated OVS bridge

If br-ex is not the right bridge for your environment, the same NNCP pattern can be used with a dedicated OVS bridge instead. Use that approach carefully, because moving an active NIC under a new bridge on a worker can break connectivity if the host networking design is not planned first.

Step 3: Create the NetworkAttachmentDefinition

Use vlan200-nad-ovn-localnet.yaml as the NetworkAttachmentDefinition.

Apply it:

oc apply -f assets/manifests/localnet/vlan200-nad-ovn-localnet.yaml
oc get network-attachment-definition -n test-net

What matters here:

• topology: localnet tells OVN-Kubernetes this is a localnet secondary network.
• physicalNetworkName: vlan200-ovn-localnet must match the localnet name from the NNCP bridge mapping.
• subnets enables OVN-managed address allocation on the secondary interface.
• netAttachDefName must match the namespace and NAD name exactly.

If your external network is VLAN-tagged, add a VLAN ID in the NAD:

"vlanID": 100

That only works if the underlay path between the worker and the physical network is prepared for that VLAN.

Step 4: Launch a test pod

Use test-nad.yaml for the sample pod. It keeps the default pod network and adds a second interface from the vlan200-ovn-localnet NAD.

Apply it:

oc apply -f assets/manifests/localnet/test-nad.yaml
oc get pod -n test-net -w

Once the pod is Running, inspect the Multus status annotation:

oc get pod test-nad -n test-net \
  -o jsonpath='{.metadata.annotations.k8s\.v1\.cni\.cncf\.io/network-status}'

You should see the default network plus the vlan200-ovn-localnet attachment.

Step 5: Exec into the pod and validate

Get an interactive shell:

oc exec -it -n test-net pod/test-nad -- sh

Inside the pod, check the interfaces:

ip addr show
ip -br addr
ip route

You should see:

• eth0 for the normal cluster pod network
• net1 for the localnet secondary network created by Multus

To inspect the secondary interface directly:

ip addr show dev net1
ip route show dev net1
ip neigh show dev net1

To test L2 and L3 connectivity on the localnet attachment:

ping -I net1 10.115.16.1
arping -I net1 10.115.16.1

Pick targets that actually exist on your external subnet. In this setup, 10.115.16.0/20 is the configured secondary network, so start with the expected gateway or another reachable host on that segment.

In a real environment that might be:

• the subnet gateway
• a legacy appliance
• a bare metal host
• a service IP reachable only from the underlay

If DNS is not part of the localnet path, test by IP first before assuming the network itself is broken.

Useful verification commands from the cluster side

These are the commands I usually run while troubleshooting:

oc get nncp
oc describe nncp br-ex-localnet
oc get nns
oc get network-attachment-definition -n test-net
oc describe pod test-nad -n test-net

To see the network-status annotation in a readable form:

oc get pod test-nad -n test-net -o json | jq '.metadata.annotations["k8s.v1.cni.cncf.io/network-status"] | fromjson'

Common failure points

When localnet does not work, the problem is usually one of these:

• The NNCP bridge mapping has not rolled out successfully to the worker nodes.
• physicalNetworkName in the NAD does not match the NNCP localnet mapping name.
• The external bridge does not actually reach the target subnet.
• The gateway IP was accidentally included in the assignable pool.
• The physical switch is not allowing the VLAN you configured in the NAD.
• The pod is running on a node that does not have the expected bridge mapping.

Final thoughts

For most clusters, I think of the choices this way:

• use OVN-Kubernetes layer2 when you only need isolated east-west connectivity
• use OVN-Kubernetes localnet when workloads need a clean path to an existing physical network
• use macvlan or bridge for simpler CNI-based attachments when OVN secondary topology is not the goal
• use SR-IOV when direct VF performance is the requirement

localnet is a strong middle ground. You keep the normal OpenShift pod networking model, but you can still attach the selected workloads that need underlay access through a second interface.

References

• OpenShift documentation: understanding multiple networks
• OVN-Kubernetes multi-homing and secondary network topologies
• Example of localnet bridge mapping and VLAN-backed NAD

What I like about this repo is that it keeps the workflow simple:

• use a Flask UI to collect the image build inputs
• query OCI dynamically for the available profiles, images, and shapes
• store each build request in SQLite
• generate a Packer template from the submitted form data
• launch a Packer build that creates a new image in OCI

That makes it less of a giant platform and more of a focused control plane for one job: turning a repeatable image customization request into an OCI image build.

What the application does

At a high level, the app gives the user a web form with these fields:

• OCI profile
• base image
• instance shape
• optional Flex shape sizing
• a package list to install

From there, the app creates a build record and starts the image build asynchronously.

The code path is straightforward:

1. The Flask app in app.py renders the build form.
2. The OCI helper functions in oci_utils.py read the local OCI CLI config and query OCI for profiles, Oracle Linux images, and shapes.
3. The form submission is stored as an ImageBuild record through SQLAlchemy in models.py.
4. A background thread calls run_packer_build to generate a JSON template and execute packer build.
5. The build status and captured output are written back to the database.

That separation is clean enough that you can understand the system quickly:

• Flask handles the UI and request lifecycle
• OCI SDK calls handle discovery
• SQLAlchemy tracks state
• Packer performs the actual image creation

The UI flow

The HTML templates are basic Bootstrap templates, which is fine for this type of tool. The important part is the user flow in templates/index.html.

When the page loads, JavaScript calls two Flask API endpoints:

• /api/images/<profile_name>
• /api/shapes/<profile_name>

Those endpoints return JSON that populates the dropdowns based on the selected OCI profile. That means the form is not hardcoded to a single environment. Instead, it uses the OCI configuration already present on the system and lets the user choose which profile to authenticate with.

The shape handling is also practical. If the selected shape contains Flex, the page reveals fields for:

• ocpus
• memory_in_gbs

That is a small touch, but it matches how OCI actually works with Flex shapes and avoids forcing those parameters for fixed-size shapes.

How the OCI integration works

The OCI-specific logic lives in oci_utils.py.

There are three main helpers:

• get_oci_profiles() parses the local OCI config file and returns the available profile names.
• get_oci_images() uses the OCI Python SDK to list available Oracle Linux images in the configured compartment.
• get_available_shapes() lists the shapes available in the compartment.

This design makes the tool tenancy-aware without forcing the user to manually paste long OCIDs into the form every time.

A few implementation details stood out to me:

• the OCI config file path is taken from ~/.oci/config
• the compartment, subnet, and availability domain are loaded from environment variables
• the image list is filtered to operating_system='Oracle Linux'

That last point is important. Right now the app is opinionated toward Oracle Linux based image builds, which is a reasonable place to start for OCI-focused automation.

How the build request is persisted

The model is intentionally small. The ImageBuild table stores:

• cloud provider
• OCI profile
• base image
• package list
• shape
• Flex sizing values when applicable
• status
• captured Packer output
• submission timestamp

For a tool like this, SQLite is a sensible default. It keeps the application lightweight and easy to run locally without requiring an external database just to track a build queue.

The app also forces the database path into the local instance directory in app.py, which avoids some of the common relative-path confusion that often shows up in simple Flask projects.

How the Packer template is generated

The most important backend logic is in packer_utils.py.

When a build starts, the code:

1. splits the submitted package list into lines
2. converts those package names into a yum install -y command
3. loads the selected OCI profile from the local OCI config
4. extracts the authentication fields Packer needs
5. builds a JSON document for the oracle-oci Packer plugin
6. writes that JSON to a temporary .pkr.json file
7. runs packer build -force

The generated provisioner is simple and clear:

"inline": [
  "sudo yum update -y",
  "sudo yum install -y ..."
]

That means the repository is currently optimized for package-based customization instead of a more general provisioning pipeline with shell scripts, Ansible, or cloud-init fragments. For many internal image-builder use cases, that is enough to be immediately useful.

Another detail I liked is that the code injects the OCI authentication fields directly into the Packer source block rather than depending on external shell state at build time. That reduces ambiguity around which OCI profile is actually being used.

Why the async build model makes sense

The application starts the Packer work in a background thread after saving the build request. That is the right tradeoff for a simple Flask app because image creation is slow and should not block the request thread while the browser waits for a response.

The build history view in templates/builds.html then gives a simple status table showing:

• build ID
• cloud
• base image
• status
• submission time

It is intentionally minimal, but it is enough to confirm that a request was queued and whether it completed or failed.

What I think this project does well

After reading the code, I think the repo does a few things particularly well:

• It keeps the problem scope tight.
• It uses OCI discovery instead of hardcoded dropdown values.
• It records build state in a way that is easy to inspect.
• It generates Packer configuration programmatically from user input.
• It supports Flex shapes, which matters in OCI.

Most importantly, it captures a workflow that many teams eventually want: “start from a known OCI image, add the packages we care about, and produce a reusable custom image.”

Where I would extend it next

The current code works as a solid first version, but reading it also made the next set of improvements pretty obvious:

• filter shapes based on base image compatibility instead of listing all shapes
• support more provisioning options than package installation alone
• add stronger validation around package input and numeric Flex fields
• surface the packer output in the UI instead of only storing it in the database
• move background execution to a real task queue if concurrency grows
• add migrations for schema changes instead of relying on ad hoc database updates

None of those points take away from the value of the current implementation. They are mostly signs that the repo has reached the stage where a working prototype can evolve into a more durable internal tool.

Final thoughts

The main idea behind oci-image-builder is practical: wrap OCI discovery and Packer execution in a small web interface so a repeatable image build becomes easier to launch and track.

That combination works well here:

• Flask provides a lightweight front end
• the OCI SDK supplies tenancy-aware discovery
• SQLAlchemy keeps build metadata
• Packer performs the actual image creation

For anyone building custom Oracle Linux based images on OCI, this is a useful pattern. You do not need a large image factory platform to get value. A small app with the right boundaries can already provide a repeatable and understandable image build workflow.

That is what oci-cap-check does. The repository is a Flask application that turns an OCI capacity-report workflow into a browser-based tool. Instead of running a long CLI flow manually every time, I can open a page on localhost:5000, connect to a tenancy, choose a shape and region, and get back a formatted capacity report.

What I was trying to solve

Capacity checks in OCI are rarely just about one value. In practice, I usually need to know:

• which subscribed regions are reachable
• which availability domains and fault domains should be checked
• whether a shape needs extra configuration such as OCPUs or memory
• whether I am querying at tenancy level or a specific compartment
• whether I want the raw availability state only or the available count as well

That makes even a simple “do I have capacity?” check more than a single API call.

The implementation in oci-cap-check is built around that reality. The app keeps the browser UI simple, but the backend still does the same OCI work I would otherwise script by hand.

Architecture at a glance

The repository is split into a few focused modules:

• app.py handles the Flask routes and page rendering
• oci_runner.py runs the reporting workflow and captures terminal-style output
• modules/identity.py handles authentication, region subscription lookup, compartment selection, and AD/FD discovery
• modules/capacity.py builds and submits compute capacity report requests
• templates/index.html provides a two-step UI for connect-then-run

That separation is useful because the web app is really a thin layer over a reusable OCI reporting flow.

The web flow

The browser flow is intentionally split into two stages.

Step 1: Connect and load tenancy data

The first form asks for:

• OCI config profile
• full OCI config file path

The current UI defaults to config-file based authentication, which maps to user_auth=cf.

When I click Connect & Load Tenancy Data, app.py:

1. calls init_authentication()
2. creates an OCI identity client
3. loads the tenancy’s subscribed regions
4. loads the available compute shapes

That data is then used to populate the dropdowns for the second form.

This is a good design choice because it prevents the user from trying to run a capacity report before the tenancy connection is actually proven to work.

Step 2: Run the capacity report

Once the tenancy data is loaded, the second form appears. It lets me choose:

• shape
• target region or all subscribed regions
• OCPUs for Flex shapes
• memory for Flex shapes
• optional compartment OCID
• tenancy-level admin mode
• DRCC mode

Submitting that form calls run_capacity_check() in oci_runner.py, which runs the full backend workflow and returns the report as text to display in the page.

How authentication works

One of the more useful parts of the repo is the authentication logic in modules/identity.py.

The backend supports multiple OCI authentication paths:

• Cloud Shell delegation token
• local OCI config file
• instance principals

For the web UI, the main path is config-file authentication. The code loads the config profile from the supplied file path, validates it, builds an OCI signer, and then confirms the login by fetching tenancy information through IdentityClient.

That validation step matters. It means the app does not just trust that the file exists. It verifies that the credentials are actually usable against OCI before it proceeds.

If every auth method fails, the underlying module still has a retry path, which comes from the original script-oriented design. In the browser flow, the main value is that the authentication errors are surfaced clearly instead of failing later during the capacity call.

Region handling

After authentication, the next problem is deciding what to check.

get_region_subscription_list() in modules/identity.py handles three cases:

• no region specified, which falls back to the home region
• a specific subscribed region
• all_regions, which expands to every subscribed region in the tenancy

That is then followed by validate_region_connectivity(), which uses a ThreadPoolExecutor to test region connectivity concurrently.

I like this part of the implementation because it avoids wasting time on a long serial check across many regions. Each region is validated by creating an identity client in that region and confirming the tenancy is reachable there. Regions that fail are reported and skipped.

In other words, the app distinguishes between:

• regions that exist
• regions the tenancy is subscribed to
• regions that are actually reachable for the current credentials

That is the right way to build a useful OCI capacity tool.

Shape handling and why it matters

Compute shapes in OCI are not all configured the same way, so a capacity checker cannot treat them all uniformly.

That logic lives in modules/capacity.py.

The implementation handles a few important cases:

• bare metal shapes
• standard Flex shapes
• DenseIO Flex shapes
• special handling for VM.Standard.A2.Flex

For fixed shapes and bare metal, the code can often rely on the shape defaults returned by OCI.

For ordinary Flex shapes, the app clamps the requested OCPUs and memory to the limits allowed by the shape metadata.

For DenseIO Flex shapes, the code uses predefined valid configurations. That is important because those shapes are not just “pick any OCPU and memory combination.” They need a valid mapping that also accounts for NVMe layout.

That extra logic is one of the places where the repository stops being a thin UI wrapper and becomes a genuinely useful implementation.

How the capacity report is built

The core OCI call is create_compute_capacity_report().

For each validated region, the backend:

1. switches the OCI client config to that region
2. fetches availability domains
3. fetches fault domains inside each AD
4. derives the correct shape configuration
5. builds CreateComputeCapacityReportDetails
6. submits a capacity report request for the shape and fault domain

The report is then printed in a table-style format that includes:

• region
• availability domain
• fault domain
• shape
• OCPU
• memory
• availability

If DRCC mode is enabled, the output also includes available_count.

That gives the app two reporting modes:

• a simpler availability view
• a more detailed count-aware view for DRCC use cases

Why I kept the output text-based

The report display in the UI is a <pre> block, not a rich data grid. That is a pragmatic choice.

The backend already had a print-oriented reporting flow, so oci_runner.py uses redirect_stdout() to capture that output into an in-memory buffer and return it to the page. That lets the same operational output format work in both script and web contexts.

For a first implementation, that is efficient:

• no need to redesign all reporting output into JSON-first rendering
• easy to preserve familiar script output
• faster to debug because the raw report remains visible

If I wanted to evolve the tool later, the next step would be to return structured data and render it as a sortable HTML table. But for an operator-facing internal tool, the captured text output is a reasonable tradeoff.

Access model and compartment handling

Another useful design point is that the app does not assume tenancy-wide admin access.

set_user_compartment() in modules/identity.py lets the workflow run in either of these modes:

• tenancy-level if the user has broader admin rights
• compartment-level if the user only has access to a specific compartment

That matters in real OCI environments where permissions are often scoped narrowly. The app also validates compartment state before running the report, which avoids misleading failures later in the flow.

What I think works well

After reading through the repo, a few implementation choices stand out as solid:

• The UI is split into a connection step and a reporting step.
• Authentication is validated early.
• Region connectivity is checked concurrently.
• Shape-specific constraints are handled explicitly instead of ignored.
• Availability domains and fault domains are expanded automatically.
• The tool supports both tenancy-level and compartment-level usage.

Those are the parts that make this more than just a demo Flask form.

What I would improve next

If I continue building on oci-cap-check, the next improvements are fairly clear:

• replace the text report with structured HTML table rendering
• remove leftover interactive CLI prompts from shared modules when running in web mode
• add stronger UI validation for Flex fields
• let the user save common report presets
• export results as CSV or JSON
• add pagination or filtering if the result set gets large across many regions

The current version already proves the main idea, though: OCI capacity checks can be wrapped in a simple browser workflow without losing the important tenancy, region, compartment, and shape logic underneath.

Final thoughts

oci-cap-check is essentially an operational script promoted into a small web application.

That is why the implementation works well. It did not start by chasing a fancy UI. It started with the real OCI tasks that matter:

• authenticate correctly
• discover the right regions
• handle shape configuration properly
• query capacity across ADs and FDs
• show the result in a format that is easy to read

For a tool meant to answer “where can I actually launch this shape?”, that is the right level of engineering.

That is exactly what oci-maintenance is built to do.

The repository is intentionally small. It is a single Python script, maint.py, backed by the OCI Python SDK. But the script captures a practical maintenance workflow:

• discover all instances flagged for maintenance reboot
• spread them into maintenance pools
• reboot one pool at a time using REBOOT_MIGRATE
• support dry runs before changing anything

What problem the script is solving

If I have a fleet spread across multiple subscribed OCI regions, a maintenance event can affect more than one place at once. I do not want to reboot everything immediately, and I do not want to sort instance lists manually every time.

I want a flow that answers three questions cleanly:

1. Which instances are currently marked for maintenance reboot?
2. How can I split them into batches for staged execution?
3. How do I reboot only the batch I am ready to move?

The design of oci-maintenance follows that exact sequence.

Structure of the repository

The repo is simple enough that the entire implementation lives in one file:

• maint.py

That script is structured around a few focused functions:

• get_config() loads OCI config and authentication details
• get_subscribed_regions() discovers the tenancy’s subscribed regions
• search_instances_needing_reboot() finds affected instances using OCI Resource Search
• list_instances() prints the currently affected instances
• assign_pools() applies a maintenance_pool freeform tag
• reboot_pool() triggers REBOOT_MIGRATE for one selected pool

The script is then exposed through a small CLI built with argparse.

Authentication and config handling

The first thing the script does is load OCI credentials from a config file.

get_config():

• expands ~ in the config path
• loads the selected profile
• extracts the configured pass_phrase if present
• returns both the config and the passphrase

The script then passes that configuration into the OCI SDK clients. One useful detail here is that the script explicitly accounts for encrypted private keys by reading the passphrase from the OCI config profile.

That is a pragmatic choice. A lot of small operational scripts fail the moment the key is encrypted or the config path is not the default one. This implementation makes those assumptions visible and configurable from the CLI.

The CLI supports:

• --config for a custom OCI config path
• --profile for a non-default profile
• --dry-run for safe previews

How affected instances are discovered

The core discovery step is in search_instances_needing_reboot().

Instead of iterating through every instance with a compute list call and then filtering in code, the script uses OCI Resource Search with a structured query:

query instance resources where timeMaintenanceRebootDue > 'Now'

That is a strong implementation choice because it lets OCI do the filtering. The script only receives the instances that matter for the maintenance workflow.

The search result gives the script the data it needs for the next steps:

• display name
• instance OCID
• availability domain
• compartment ID
• freeform tags

Multi-region coverage

After loading credentials, the script uses IdentityClient.list_region_subscriptions() to retrieve all subscribed regions in the tenancy.

That region list is then used in each of the main workflows:

• listing instances
• assigning pools
• rebooting a pool

For each region, the script creates a region-specific client configuration and runs the maintenance search there.

That matters because maintenance actions are often distributed across regions, and the script is clearly designed to work at tenancy scope instead of assuming a single-region environment.

Listing instances that need reboot

The list command is the read-only entry point:

python maint.py --profile CVM list

list_instances():

1. loads the OCI config
2. gets the subscribed regions
3. searches each region for instances where timeMaintenanceRebootDue > 'Now'
4. collects those results into a single list
5. prints a readable table

The printed output includes:

• region
• instance name
• OCID
• availability domain
• current maintenance pool tag

That last value is important because it lets the listing serve two purposes:

• identify maintenance candidates
• confirm how they are currently staged

Assigning maintenance pools

The next operational step is controlled rollout.

That logic lives in assign_pools().

The command takes a pool count:

python maint.py --profile CVM --dry-run assign-pools --num-pools 3

The implementation does a few useful things:

• gathers all affected instances across regions
• sorts them by OCID for deterministic ordering
• assigns pool numbers in round-robin fashion
• writes the result into the maintenance_pool freeform tag

The round-robin assignment is simple:

new_pool = str((i % num_pools) + 1)

That means if I choose three pools, the script will distribute the affected instances across pool 1, 2, and 3 in a stable sequence.

The tagging model is also practical because it stores rollout state directly on the instance as metadata. Once the tags exist, the reboot step can use them without maintaining a separate inventory file.

Why dry-run matters here

assign_pools() has a dry-run branch that prints the assignments without updating any tags.

That is exactly what I want for a maintenance script. Before changing anything, I can see:

• which instances would be placed in which pool
• whether an instance is already in the expected pool
• whether the chosen pool count produces a sensible distribution

For operational tooling, dry-run support is one of the highest-value safety features, and this script includes it in the right places.

Rebooting one pool at a time

Once pools are assigned, reboot_pool() handles the execution step.

Its job is:

1. search the affected instances again across subscribed regions
2. filter only the instances whose maintenance_pool tag matches the requested pool number
3. issue an OCI instance action of REBOOT_MIGRATE

Example usage:

python maint.py --profile CVM reboot-pool --pool 2

Or safer:

python maint.py --profile CVM --dry-run reboot-pool --pool 2

That workflow is a good operational pattern because it makes the reboot stage explicit and auditable. The maintenance pool tag is the handshake between planning and execution.

The actual OCI action used

The script does not perform a generic reboot. It specifically calls:

compute_client.instance_action(inst['ocid'], 'REBOOT_MIGRATE')

That matters because the whole utility is about OCI maintenance-related reboot migration, not arbitrary instance restarts.

So the implementation aligns with the operational intent:

• discover instances flagged for maintenance
• use the maintenance-specific reboot action

Error handling and observability

The script is direct rather than elaborate, but it does include useful debug output.

It prints:

• config path being used
• profile being loaded
• whether a passphrase was found
• region-specific client initialization
• success or failure of update and reboot operations

For small operations tooling, that is often enough. The script is not trying to be a full logging platform. It is trying to be debuggable when run by an operator.

It also catches ServiceError around the mutating OCI operations so an update or reboot failure for one instance is reported clearly.

What I think works well in this implementation

After reading the code, a few design choices stand out:

• OCI Resource Search is used to discover only the instances that matter.
• Region coverage is handled automatically through subscribed region discovery.
• Pool assignment is deterministic because the instance list is sorted.
• Rollout state is stored as a freeform tag on the instance.
• Dry-run exists for both assignment and reboot flows.
• The reboot action is maintenance-specific rather than generic.

That gives the script a clear operational lifecycle:

• observe
• stage
• execute

Where I would extend it next

If I were taking this further, the next improvements would probably be:

• add concurrency for tag updates and reboot actions
• add CSV or JSON export for the list command
• include compartment name in the printed report
• add filters for region, AD, or tag scope
• add a summary count per pool before execution
• add retry behavior or waiter logic for reboot tracking

None of those are required for the current script to be useful. The existing implementation already does the main job well.

Final thoughts

oci-maintenance is a good example of a small operational utility that solves a concrete problem without overengineering it.

It does not try to be a full fleet management platform. Instead, it focuses on a narrow and valuable maintenance workflow:

• find the instances OCI says need reboot migration
• group them into staged pools
• execute those reboots one pool at a time

For a script that lives in a single file, that is a solid implementation boundary.