Practical notes: Building a Private Cloud Coding Agent: OpenCode + a Local LLM
Operable walkthrough of Practical notes: Building a Private Cloud Coding Agent: OpenCode + a Local LLM: contracts, checks, and drop-in code slots for teams shipping this pattern.
This article is published in English.
Sources: Building a Private Cloud Coding Agent: OpenCode + a Local LLM, Running on Serverless GPUs
The following notes reconstruct a practical path around “Building a Private Cloud Coding Agent: OpenCode + a Local LLM, Running on Serverless GPUs”. Emphasis stays on contracts, checks, and drop-in code placeholders rather than motivational framing. When working through the Overview stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Why this architecture
Why this architecture works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
The building blocks
The building blocks works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
Modal
Modal works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices. Modal works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Ollama
For the Ollama stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Separate client construction from the message loop so providers can be swapped without rewriting the conversation state machine.
OpenCode
For the OpenCode stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
The tunnel
For the The tunnel stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call. For the The tunnel stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Prerequisites and setup
When working through the Prerequisites and setup stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.
pip install modal
modal setup
Designing the container image
When working through the Designing the container image stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.
import modal
image = (
modal.Image.from_registry(
"nvidia/cuda:13.0.0-devel-ubuntu24.04",
add_python="3.12",
)
.apt_install(
"curl",
"git",
"ca-certificates",
"zstd",
)
.run_commands(
"curl -fsSL https://ollama.com/install.sh | sh",
)
.run_commands(
"curl -fsSL https://opencode.ai/install | bash",
)
.env(
{
"OLLAMA_MODELS": "/models/.ollama/models",
"OLLAMA_HOST": "127.0.0.1:11434",
"PATH": "/root/.opencode/bin:/usr/local/bin:/usr/bin:/bin",
}
)
)
The startup script: orchestrating Ollama and OpenCode
When working through the The startup script orchestrating stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Log request id, model id, and latency on every call. Without that trail, intermittent provider errors look like application bugs. When working through the The startup script orchestrating stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Step 1 — Start Ollama in the background, verify the process didn’t immediately die
The Step 1 Start Ollama stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Pin the interpreter and dependency lockfile before teaching the loop. Drift between laptop and CI is the most common silent break for API demos.
ollama serve > /tmp/ollama.log 2>&1 &
OLLAMA_PID=$!
sleep 3
if ! kill -0 "$OLLAMA_PID" 2>/dev/null; then
echo "OLLAMA FAILED TO START"
cat /tmp/ollama.log
exit 1
fi
Step 2 — Poll until the API is actually serving, not just running
The Step 2 Poll until stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
READY=0
for i in $(seq 1 120); do
if curl -sf http://127.0.0.1:11434/api/tags > /dev/null 2>&1; then
READY=1
echo "Ollama is ready."
break
fi
sleep 1
done
if [ "$READY" != "1" ]; then
echo "Ollama failed to start."
cat /tmp/ollama.log
exit 1
fi
Step 3 — Pull the model, but only if it’s not already there
The Step 3 Pull the stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
if ollama list | grep -F "qwen3-coder" > /dev/null 2>&1; then
echo "Model already exists:"
ollama list
else
echo "Downloading: qwen3-coder:30b"
ollama pull "qwen3-coder:30b"
fi
The Step 3 Pull the stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Step 4 — Clone the repository, with a real failure path
For the Step 4 Clone the stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
if [ ! -d /workspace/.git ]; then
if GIT_TERMINAL_PROMPT=0 git clone \
--branch "main" \
--depth 1 \
"https://github.com/yourname/yourrepo.git" \
/workspace
then
echo "Clone succeeded."
else
echo "WARNING: git clone failed. Continuing without the repo."
mkdir -p /workspace
fi
else
echo "Repository already exists."
fi
Step 5 — Write OpenCode’s configuration
For the Step 5 Write OpenCode stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
mkdir -p /root/.config/opencode
cat > /root/.config/opencode/opencode.json <<'EOF'
{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/qwen3-coder:30b",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama - Qwen3 Coder 30B",
"options": {
"baseURL": "http://127.0.0.1:11434/v1"
},
"models": {
"qwen3-coder:30b": {
"name": "Qwen3-Coder 30B",
"limit": {
"context": 32768,
"output": 16384
}
}
}
}
}
}
EOF
Step 6 — Start OpenCode in the foreground
For the Step 6 Start OpenCode stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
exec opencode serve \
--hostname 0.0.0.0 \
--port 4096 \
--print-logs
For the Step 6 Start OpenCode stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Persisting model weights
When working through the Persisting model weights stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.
volume = modal.Volume.from_name(
"opencode-ollama-models",
create_if_missing=True,
)
volumes={
"/models": volume,
},
Creating the sandbox
When working through the Creating the sandbox stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.
def create_sandbox():
script = startup_script()
secrets = []
if GITHUB_REPO_IS_PRIVATE:
secrets.append(modal.Secret.from_name(GITHUB_SECRET_NAME))
sandbox = modal.Sandbox.create(
"bash", "-lc", script,
app=app,
image=image,
gpu="H100",
cpu=8,
memory=32768,
secrets=secrets,
timeout=12 * 60 * 60,
idle_timeout=300,
volumes={"/models": volume},
encrypted_ports=[OPENCODE_PORT],
workdir="/workspace",
)
return sandbox
Handling private repositories
When working through the Handling private repositories stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn. When working through the Handling private repositories stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
modal secret create github-token GITHUB_TOKEN=ghp_your_token_here
if GITHUB_REPO_IS_PRIVATE:
secrets.append(modal.Secret.from_name("github-token"))
clone_url = f"https://${{GITHUB_TOKEN}}@github.com/{GITHUB_REPO}.git"
The local entrypoint: keeping the sandbox alive
The The local entrypoint keeping stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
try:
while True:
time.sleep(5)
returncode = sandbox.poll()
if returncode is not None:
print(f"Sandbox process exited with code {returncode}.")
break
except KeyboardInterrupt:
print("Ctrl+C received. Terminating sandbox...")
sandbox.terminate()
modal run --detach opencode.py
modal shell sb-abc123xyz
The full implementation
The full implementation works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.
import time
import modal
# ============================================================
# Configuration
# ============================================================
APP_NAME = "opencode-ollama"
MODEL = "qwen3-coder:30b"
OPENCODE_PORT = 4096
OLLAMA_PORT = 11434
VOLUME_NAME = "opencode-ollama-models"
# Set this to the repo you want cloned into the sandbox.
# Leave as None or "" to skip cloning entirely.
GITHUB_REPO = "yourusername/your-repository"
GITHUB_BRANCH = "main"
# If GITHUB_REPO is private, create a Modal Secret containing
# a GitHub Personal Access Token (fine-grained, read-only, scoped
# to this one repo) with:
# modal secret create github-token GITHUB_TOKEN=ghp_xxx
# and set this to True.
GITHUB_REPO_IS_PRIVATE = False
GITHUB_SECRET_NAME = "github-token"
# ============================================================
# Modal app + persistent volume
# ============================================================
app = modal.App(APP_NAME)
volume = modal.Volume.from_name(
VOLUME_NAME,
create_if_missing=True,
)
# ============================================================
# Container image
# ============================================================
image = (
modal.Image.from_registry(
"nvidia/cuda:13.0.0-devel-ubuntu24.04",
add_python="3.12",
)
.apt_install(
"curl",
"git",
"ca-certificates",
"zstd",
)
.run_commands(
"curl -fsSL https://ollama.com/install.sh | sh",
)
.run_commands(
"curl -fsSL https://opencode.ai/install | bash",
)
.env(
{
"OLLAMA_MODELS": "/models/.ollama/models",
"OLLAMA_HOST": "127.0.0.1:11434",
"PATH": "/root/.opencode/bin:/usr/local/bin:/usr/bin:/bin",
}
)
)
# ============================================================
# Sandbox startup script
# ============================================================
def startup_script():
repo_setup = ""
if GITHUB_REPO:
if GITHUB_REPO_IS_PRIVATE:
clone_url = (
f"https://${{GITHUB_TOKEN}}@github.com/{GITHUB_REPO}.git"
)
else:
clone_url = f"https://github.com/{GITHUB_REPO}.git"
repo_setup = f"""
echo "=============================================="
echo "Cloning repository"
echo "=============================================="
nvidia-smi || true
if [ ! -d /workspace/.git ]; then
if GIT_TERMINAL_PROMPT=0 git clone \\
--branch "{GITHUB_BRANCH}" \\
--depth 1 \\
"{clone_url}" \\
/workspace
then
echo "Clone succeeded."
else
echo ""
echo "=============================================="
echo "WARNING: git clone failed."
echo "=============================================="
echo "This is usually because the repository is"
echo "private (set GITHUB_REPO_IS_PRIVATE = True and"
echo "attach a token) or the repo/branch name is"
echo "wrong. Continuing without the repo so OpenCode"
echo "still starts."
echo ""
mkdir -p /workspace
fi
else
echo "Repository already exists."
fi
"""
else:
repo_setup = """
echo "=============================================="
echo "No GitHub repository configured"
echo "=============================================="
mkdir -p /workspace
"""
return f"""
#!/bin/bash
set -e
echo "=============================================="
echo "Modal OpenCode + Ollama"
echo "=============================================="
echo "Model: {MODEL}"
echo "OpenCode port: {OPENCODE_PORT}"
echo "Ollama port: {OLLAMA_PORT}"
# ------------------------------------------------------------
# Ollama model directory
# ------------------------------------------------------------
mkdir -p /models/.ollama/models
export OLLAMA_MODELS=/models/.ollama/models
export OLLAMA_HOST=127.0.0.1:11434
# ------------------------------------------------------------
# Start Ollama
# ------------------------------------------------------------
echo ""
echo "Starting Ollama..."
ollama serve \\
> /tmp/ollama.log \\
2>&1 &
OLLAMA_PID=$!
sleep 3
if ! kill -0 "$OLLAMA_PID" 2>/dev/null; then
echo ""
echo "=============================================="
echo "OLLAMA FAILED TO START"
echo "=============================================="
echo ""
cat /tmp/ollama.log
echo ""
exit 1
fi
echo "Ollama PID: $OLLAMA_PID"
# ------------------------------------------------------------
# Wait for Ollama to be ready
# ------------------------------------------------------------
echo ""
echo "Waiting for Ollama..."
READY=0
for i in $(seq 1 120); do
if curl -sf \\
http://127.0.0.1:11434/api/tags \\
> /dev/null 2>&1
then
READY=1
echo "Ollama is ready."
break
fi
sleep 1
done
if [ "$READY" != "1" ]; then
echo ""
echo "Ollama failed to start."
echo ""
cat /tmp/ollama.log
exit 1
fi
# ------------------------------------------------------------
# Pull the model (skipped if already present in the volume)
# ------------------------------------------------------------
echo ""
echo "=============================================="
echo "Checking Ollama model"
echo "=============================================="
if ollama list | grep -F \\
"qwen3-coder" \\
> /dev/null 2>&1
then
echo "Model already exists:"
ollama list
else
echo ""
echo "Model not found."
echo ""
echo "Downloading:"
echo " {MODEL}"
echo ""
echo "This can take some time on first startup."
echo ""
ollama pull "{MODEL}"
fi
echo ""
echo "=============================================="
echo "Available Ollama models"
echo "=============================================="
ollama list
# ------------------------------------------------------------
# Repository
# ------------------------------------------------------------
{repo_setup}
cd /workspace
# ------------------------------------------------------------
# OpenCode configuration
# ------------------------------------------------------------
mkdir -p /root/.config/opencode
cat > /root/.config/opencode/opencode.json <<'EOF'
{{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/{MODEL}",
"provider": {{
"ollama": {{
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama - Qwen3 Coder 30B",
"options": {{
"baseURL": "http://127.0.0.1:11434/v1"
}},
"models": {{
"{MODEL}": {{
"name": "Qwen3-Coder 30B",
"limit": {{
"context": 32768,
"output": 16384
}}
}}
}}
}}
}}
}}
EOF
echo ""
echo "=============================================="
echo "OpenCode configuration"
echo "=============================================="
cat /root/.config/opencode/opencode.json
# ------------------------------------------------------------
# Start OpenCode
# ------------------------------------------------------------
echo ""
echo "=============================================="
echo "Starting OpenCode server"
echo "=============================================="
exec opencode serve \\
--hostname 0.0.0.0 \\
--port {OPENCODE_PORT} \\
--print-logs
"""
# ============================================================
# Create Sandbox
# ============================================================
def create_sandbox():
script = startup_script()
secrets = []
if GITHUB_REPO_IS_PRIVATE:
secrets.append(modal.Secret.from_name(GITHUB_SECRET_NAME))
sandbox = modal.Sandbox.create(
"bash",
"-lc",
script,
app=app,
image=image,
gpu="H100",
cpu=8,
memory=32768,
secrets=secrets,
timeout=12 * 60 * 60,
idle_timeout=300,
volumes={
"/models": volume,
},
encrypted_ports=[
OPENCODE_PORT,
],
workdir="/workspace",
)
return sandbox
# ============================================================
# Local entrypoint
# ============================================================
@app.local_entrypoint()
def main():
print()
print("==============================================")
print("Creating Modal Sandbox")
print("==============================================")
print()
sandbox = create_sandbox()
print()
print("Sandbox created:")
print(sandbox.object_id)
print()
print("Waiting for OpenCode server...")
print()
time.sleep(5)
tunnel_url = None
try:
tunnels = sandbox.tunnels()
tunnel = tunnels[OPENCODE_PORT]
tunnel_url = tunnel.url
print()
print("==============================================")
print("OPEN CODE IS READY")
print("==============================================")
print()
print("Sandbox ID (save this to reconnect):")
print(sandbox.object_id)
print()
print("Browser:")
print()
print(tunnel_url)
print()
print("Your OpenCode server is backed by:")
print()
print(" Ollama")
print(" Qwen3-Coder 30B")
print()
print("Ollama endpoint (inside the sandbox only):")
print("http://127.0.0.1:11434")
print()
print("==============================================")
print()
except Exception as e:
print()
print("Sandbox started, but tunnel information")
print("could not be retrieved automatically.")
print()
print(f"Error: {e}")
print()
print("The Sandbox ID is:")
print(sandbox.object_id)
print("Sandbox is running. Press Ctrl+C to stop it.")
print("(Run with `modal run --detach opencode.py` to keep")
print(" it alive after you disconnect.)")
print()
try:
while True:
time.sleep(5)
returncode = sandbox.poll()
if returncode is not None:
print(f"Sandbox process exited with code {returncode}.")
break
except KeyboardInterrupt:
print()
print("Ctrl+C received. Terminating sandbox...")
sandbox.terminate()
print("Sandbox terminated.")
Running it
Running it works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices. Running it works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
modal run opencode.py
==============================================
OPEN CODE IS READY
==============================================
Sandbox ID (save this to reconnect):
sb-abc123xyz
Browser:
https://your-generated-subdomain-4096.modal.host
modal run --detach opencode.py
modal shell sb-abc123xyz
sandbox = modal.Sandbox.from_id("sb-abc123xyz")
sandbox.terminate()
Extending the system
For the Extending the system stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
Security considerations
For the Security considerations stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
Conclusion
For the Conclusion stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call. For the Conclusion stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Operational checklist
For the Operational checklist stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state.
Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.
Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.
Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.
Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.
Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Favor boring reliability over clever one-off demos.
Batch note for 0b5d2687b03c: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.
For the hardening note 0 stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.
Hardening detail 0/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
When working through the hardening note 1 stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Hardening detail 1/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
hardening note 2 works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
Hardening detail 2/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
For the hardening note 3 stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.
Hardening detail 3/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
When working through the hardening note 4 stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.
Hardening detail 4/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
hardening note 5 works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.
Hardening detail 5/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
For the hardening note 6 stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.
Hardening detail 6/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
When working through the hardening note 7 stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.
Hardening detail 7/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
hardening note 8 works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.
Hardening detail 8/810: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.
Rewrite marker 1 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 2 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 3 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 4 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 5 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 6 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 7 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 8 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 9 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.
Rewrite marker 10 for 0b5d2687b03c: rephrase surrounding claims with operator language, keep [[CODE_n]] slots intact, and avoid echoing source sentences.