DEV Community: Pushpum Vats

Securing a VPS in 2026: A No-Nonsense Hardening Guide

Pushpum Vats — Sat, 22 Aug 2026 06:32:34 +0000

Every step ranked by priority — SSH, firewall, patching, backups, and TLS, with the exact configs.

A default VPS install is not a secure one. The moment it gets a public IP, automated bots start probing it for weak SSH logins, open ports, and outdated packages — often within minutes. This guide is ordered by impact: do Tier 1 before anything touches production, Tier 2 within the first week, Tier 3 if it applies to your stack, and Tier 4 on a recurring schedule forever. Written for Ubuntu 24.04 LTS / Debian 12, with notes where RHEL-based systems (AlmaLinux, Rocky) differ.

Tier 1 — Before Anything Touches Production

1. Non-Root User + SSH Key Auth

# On the server, as root
adduser deploy
usermod -aG sudo deploy

# On your local machine — generate a modern key (Ed25519, not RSA)
ssh-keygen -t ed25519 -C "you@yourdomain.com" -a 100

# Copy it to the server
ssh-copy-id -i ~/.ssh/id_ed25519.pub deploy@your-server-ip

# Log in as deploy, confirm sudo works, THEN lock root
sudo passwd -l root

Ed25519 keys are smaller, faster, and free of the timing side-channels that affect RSA. Use RSA only if you're stuck supporting a legacy client, and if so use at least 4096 bits.

2. Harden sshd_config

Keep a second terminal connected while you test — don't edit this over your only session. Edit /etc/ssh/sshd_config (or drop a file into /etc/ssh/sshd_config.d/):

# Authentication
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
KbdInteractiveAuthentication no
PermitEmptyPasswords no
MaxAuthTries 3
MaxSessions 4
LoginGraceTime 30
AllowUsers deploy

# Modern crypto only — drop legacy KEX/ciphers/MACs
KexAlgorithms mlkem768x25519-sha256,curve25519-sha256,[email protected]
HostKeyAlgorithms ssh-ed25519,ecdsa-sha2-nistp256
Ciphers [email protected],[email protected],[email protected]
MACs [email protected],[email protected]

# Reduce attack surface
X11Forwarding no
AllowAgentForwarding no
AllowTcpForwarding no
ClientAliveInterval 300
ClientAliveCountMax 2

Notes:

mlkem768x25519-sha256 is a hybrid classical/post-quantum key exchange (ML-KEM-768, FIPS 203) and is the default negotiated exchange on OpenSSH 9.9+. It protects against "harvest now, decrypt later" interception. If anything in your fleet runs older OpenSSH, drop that entry and lead with curve25519-sha256.
Restart safely: sudo systemctl reload sshd (reload, not restart, keeps existing sessions alive if the config is bad).
Run sshd -T | less to see the effective config, and audit it externally with ssh-audit your-server-ip — it flags any weak KEX, cipher, or MAC still active.
Changing the port off 22 doesn't stop a targeted attacker, but it silences almost all automated scanner noise in your logs. Optional, not a substitute for the above.

3. Firewall: Default Deny

sudo apt install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH        # or: sudo ufw allow 2222/tcp if you changed the port
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

UFW (and firewalld on RHEL-based distros) both drive nftables under the hood now — the old iptables chains are a legacy compatibility layer, not your primary interface anymore. For anything beyond simple port rules, nft directly gives finer control, but UFW covers the vast majority of single-VPS setups.

4. Automatic Security Patching

The gap between a CVE disclosure and your patch is where breaches happen — the 2024 OpenSSH "regreSSHion" RCE (CVE-2024-6387) was weaponized within days. Close that gap automatically:

sudo apt install unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades

In /etc/apt/apt.conf.d/50unattended-upgrades, stick to the security pocket, blacklist anything you'd rather patch by hand, and schedule reboots for a known-quiet window:

Unattended-Upgrade::Allowed-Origins {
    "${distro_id}:${distro_codename}-security";
};
Unattended-Upgrade::Package-Blacklist {
    "postgresql-*";
    "linux-image-*";
};
Unattended-Upgrade::Automatic-Reboot "true";
Unattended-Upgrade::Automatic-Reboot-Time "04:00";
Unattended-Upgrade::Mail "you@yourdomain.com";
Unattended-Upgrade::MailReport "on-change";

Confirm the -security pocket is active in /etc/apt/apt.conf.d/20auto-upgrades, and dry-run after any edit: sudo unattended-upgrade --dry-run -v. For zero-downtime kernel patching, Canonical's Livepatch service is free for up to 5 machines.

5. Backups — Set Up Before You Need Them

Hardening reduces the odds of compromise; it doesn't make you immune, and it does nothing for hardware failure or a bad rm -rf. Follow the 3-2-1 rule: 3 copies of your data, on 2 different media, with 1 off-site.

# restic example — encrypted, deduplicated, incremental
restic init --repo s3:s3.amazonaws.com/your-backup-bucket
restic backup /etc /home /var/www --repo s3:s3.amazonaws.com/your-backup-bucket

Automate it with a systemd timer or cron, and put a restore drill on your calendar now — a backup you haven't test-restored isn't a backup.

Tier 2 — Within the First Week

6. Intrusion Banning: Fail2Ban (+ CrowdSec if you're scaling)

Fail2Ban — simple, ~15 MB RAM, the right default for one server:

sudo apt install fail2ban
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

Edit /etc/fail2ban/jail.local:

[DEFAULT]
bantime  = 1h
findtime = 10m
maxretry = 3
backend  = systemd
banaction = nftables-multiport

[sshd]
enabled = true
port    = 2222

sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

CrowdSec is worth adding once you're running more than one box, or want protection against attackers before they've hit your logs — it shares crowd-sourced IP reputation across its network via lightweight "bouncers" that write directly into nftables sets. Common pattern: Fail2Ban for SSH, CrowdSec for the web-facing layer (its Nginx/Caddy bouncer integrations are solid). They coexist fine as long as they're not both managing the exact same log source.

7. Kernel Network Hardening

Create /etc/sysctl.d/99-hardening.conf:

net.ipv4.tcp_syncookies = 1
net.ipv4.conf.all.accept_source_route = 0
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.all.rp_filter = 1
net.ipv4.icmp_echo_ignore_broadcasts = 1
net.ipv6.conf.all.accept_redirects = 0
kernel.dmesg_restrict = 1

sudo sysctl --system

8. File Permissions & Mandatory Access Control

# Sane default umask for new files
echo "umask 027" | sudo tee -a /etc/profile.d/umask.sh

# Find unexpected SUID/SGID binaries — investigate anything you don't recognize
sudo find / -xdev -perm -4000 -o -perm -2000 2>/dev/null

# Confirm AppArmor is enforcing (Ubuntu/Debian default MAC)
sudo aa-status

On RHEL-based systems, use sestatus and keep SELinux in Enforcing mode rather than switching to Permissive to make an install easier — fix the policy instead.

9. Full-Disk Encryption (LUKS)

Protects data at rest if a drive is stolen, misconfigured, or decommissioned by a third party — relevant on any VPS since the underlying storage is managed by your provider, not you. It's best enabled during the OS install; encrypting an existing root filesystem in place is disruptive and rarely worth it. For existing servers, focus on encrypting a dedicated data or backup partition instead — and note that restic/borgbackup already encrypt archives at rest, so your Tier 1 backups are covered either way.

10. Database Hardening

If you're running MySQL/MariaDB or PostgreSQL on the same box, don't expose it publicly and don't use superuser accounts for application connections:

# MySQL/MariaDB — /etc/mysql/mariadb.conf.d/50-server.cnf
[mysqld]
bind-address = 127.0.0.1

# PostgreSQL — postgresql.conf
listen_addresses = 'localhost'

-- Least-privilege app user, MySQL example
CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'strong-random-password';
GRANT SELECT, INSERT, UPDATE, DELETE ON app_db.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;

Run mysql_secure_installation (or the PostgreSQL equivalent of removing default/trust auth) to kill anonymous accounts and remote root. If a second server genuinely needs DB access, restrict it by source IP in your firewall rather than binding to 0.0.0.0.

Tier 3 — If It Applies to Your Stack

11. TLS: Get an A+ Without Guessing

If you're terminating TLS on the box (Nginx, Caddy, Apache), use Let's Encrypt with auto-renewal and Mozilla's current Intermediate profile — TLS 1.2 + 1.3 only, no legacy DHE ciphers, every suite forward-secret and AEAD:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
sudo systemctl list-timers | grep certbot   # confirm the renewal timer is active

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;

add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
add_header X-Content-Type-Options nosniff always;
add_header X-Frame-Options SAMEORIGIN always;
server_tokens off;

# Basic request-rate protection against scraping/brute force at the app layer
limit_req_zone $binary_remote_addr zone=basic:10m rate=10r/s;
limit_req zone=basic burst=20 nodelay;

ssl_prefer_server_ciphers off is intentional, not an oversight — every cipher in the Intermediate list is already strong, so letting the client pick lets mobile devices without AES hardware acceleration negotiate ChaCha20 instead. Only add the HSTS preload flag if every subdomain will always serve HTTPS — removal from browser preload lists takes months.

One 2026-specific note: public CA certificate lifetimes are shortening (down to 200 days as of March 2026, and heading lower over the next few years), so make sure renewal is genuinely automated rather than a calendar reminder — verify with sudo certbot renew --dry-run.

12. SSH at Scale: Certificates and TOTP 2FA

A single-admin box is fine with one hardware or software key. Once more than one or two people need access, static keys in authorized_keys become an operational liability — nobody remembers to remove them when someone leaves.

SSH certificates replace that with short-lived, centrally-issued credentials:

# One-time: create a CA keypair, keep the private half offline
ssh-keygen -t ed25519 -f ssh-user-ca -C "internal CA"

# Sign a user's key for 24 hours, scoped to a principal
ssh-keygen -s ssh-user-ca -I alice-daily -n alice,ops -V +24h alice_id_ed25519.pub

# /etc/ssh/sshd_config
TrustedUserCAKeys /etc/ssh/ca/trusted_user_ca.pub

Revoking access is then just "stop issuing certificates for that principal" instead of hunting down every server's authorized_keys file.

TOTP 2FA is the lower-cost option if hardware keys aren't practical for your team:

sudo apt install libpam-google-authenticator
google-authenticator   # run as the user; save the printed backup codes

# /etc/pam.d/sshd — replace the @include common-auth line
auth required pam_google_authenticator.so

# sshd_config
KbdInteractiveAuthentication yes
AuthenticationMethods publickey,keyboard-interactive

This forces both a valid key and a TOTP code. It's not as phishing-resistant as FIDO2, but it's a meaningful step up from key-only auth for teams that don't want to distribute hardware tokens.

Going portless entirely is worth a look once you're managing more than a couple of servers: Tailscale SSH authenticates sessions over an already-authenticated WireGuard mesh with no inbound port required at all, and AWS SSM Session Manager / GCP IAP TCP forwarding offer the same idea gated by cloud IAM instead of network exposure.

13. Docker Container Security

Run containers as a non-root user (USER directive in the Dockerfile), never --privileged.
Don't mount /var/run/docker.sock into a container unless that container's entire job is orchestration — it's root-equivalent access to the host.
Set read_only: true and mount an explicit tmpfs for anything that needs to write.
In /etc/docker/daemon.json, disable inter-container communication you don't need and consider userns-remap so container root maps to an unprivileged host UID:
```
{
  "icc": false,
  "userns-remap": "default",
  "no-new-privileges": true
}
```
Keep base images current; rebuild on a schedule so you're not shipping stale CVEs, and scan with docker scout or Trivy before deploying.
Fail2Ban doesn't play well with Docker's own iptables/nftables management — most people run it on the host watching host logs rather than trying to containerize it.

14. Systemd Sandboxing for Non-Containerized Services

If an app runs directly as a systemd unit rather than in a container, you can get most of the isolation Docker would give you for free:

[Service]
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/myapp
MemoryMax=768M
CapabilityBoundingSet=

This limits blast radius — a compromised or buggy service can't read arbitrary paths, escalate privileges, or take down the host by exhausting memory. Check what a unit is actually doing with systemd-analyze security <unit>, which scores its exposure and flags missing sandboxing directives.

Tier 4 — Ongoing, Forever

15. Logging, Auditing, and Rootkit Checks

sudo apt install auditd lynis rkhunter

# Watch the files attackers actually touch
sudo tee -a /etc/audit/rules.d/audit.rules <<'EOF'
-w /etc/passwd -p wa -k identity
-w /etc/shadow -p wa -k identity
-w /etc/sudoers -p wa -k sudoers
-w /etc/ssh/sshd_config -p wa -k sshd_config
-w /root/.ssh/authorized_keys -p wa -k ssh_keys
EOF
sudo systemctl restart auditd

# Full posture audit
sudo lynis audit system

# Rootkit scan
sudo rkhunter --check

Antivirus isn't a meaningful control on a Linux server — proper hardening, patching, and log review outperform it. Skip it and spend the time here instead.

16. Maintenance Cadence

Configuration drifts. Put this on a recurring calendar block:

Weekly — review Fail2Ban/CrowdSec ban logs, confirm unattended-upgrades ran cleanly, check df -h and disk usage trends.
Monthly — audit user accounts and sudoers, review ss -tlnp for services listening that shouldn't be, run lynis audit system and act on new warnings.
Quarterly — rotate SSH keys/certificates and any long-lived credentials, re-run ssh-audit and a TLS scan (SSL Labs or testssl.sh), test a full backup restore.

Quick Checklist

Tier 1 — before production traffic:

Root login disabled, sudo user created, key-based SSH only
sshd_config hardened: modern KEX/ciphers, MaxAuthTries 3, no forwarding
Firewall default-deny, only required ports open
unattended-upgrades installed, security pocket only, tested with --dry-run
Automated, encrypted, off-site backups — restore-tested

Tier 2 — first week:

Fail2Ban (or CrowdSec) active and tested
Kernel sysctl hardening applied
AppArmor/SELinux enforcing, sane umask, SUID audit done
Full-disk or backup-archive encryption confirmed
Database bound to localhost, least-privilege app user

Tier 3 — if applicable:

TLS on Mozilla Intermediate profile, auto-renewing certs, HSTS enabled
SSH certificates or TOTP 2FA in place for multi-admin access
Docker containers non-root, no exposed socket, images kept current
systemd sandboxing applied to bare-metal services

Tier 4 — recurring:

auditd watching critical files, Lynis/rkhunter scans scheduled
Weekly/monthly/quarterly maintenance cadence on the calendar

Run Tier 1 on every new server before it touches production traffic. The rest isn't optional so much as scheduled — security is a habit you keep paying into, not a setup you finish.

Originally published on ZyVOP

💡 For more articles like this, subscribe to the ZyVOP newsletter!

I Built a Tiny AI Agent From Scratch — Every Line Tested Before It Touched a Real API

Pushpum Vats — Sat, 22 Aug 2026 06:30:27 +0000

What an "agent" actually is, stripped of the hype

Every few weeks there's a new framework promising to make "agentic AI" easy. Most of them are wrappers around one core idea: the model doesn't just generate text — it can pause, say "I need to call this function with these arguments," wait for the result, and then keep going with that information in hand.

That's it. That's the whole trick. Anthropic calls this tool use, and it's the same mechanism powering everything from "let Claude check the weather" to multi-step coding agents.

This tutorial builds a working version of that loop from the ground up — no LangChain, no agent framework, just the Claude API and plain Python. By the end you'll have a small agent that can do arithmetic and count words by actually calling real Python functions, decide on its own when to use them, and chain them together when a question needs both.

What you'll need

Python 3.9 or newer
An Anthropic API key (from the Claude Console)
The official SDK: pip install anthropic

That's the whole list. No vector databases, no Docker, nothing else.

Step 1: Write the actual tools (just functions)

This is the part people often overcomplicate. A "tool" is just a regular Python function, plus a small JSON description telling Claude what it does and what arguments it takes.

We'll build two: a calculator and a word counter. Save this as tools.py:

"""
The actual Python functions our agent can call, plus the JSON-schema
descriptions of those tools that we hand to the Claude API.
"""

import ast
import operator

_OPS = {
    ast.Add: operator.add,
    ast.Sub: operator.sub,
    ast.Mult: operator.mul,
    ast.Div: operator.truediv,
    ast.Pow: operator.pow,
    ast.USub: operator.neg,
}

def calculate(expression: str) -> str:
    """Safely evaluate a basic arithmetic expression like '12 * (3 + 4)'."""

    def _eval(node):
        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
            return node.value
        if isinstance(node, ast.BinOp) and type(node.op) in _OPS:
            return _OPS[type(node.op)](_eval(node.left), _eval(node.right))
        if isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:
            return _OPS[type(node.op)](_eval(node.operand))
        raise ValueError(f"Unsupported expression: {expression!r}")

    tree = ast.parse(expression, mode="eval")
    result = _eval(tree.body)
    return str(result)

def count_words(text: str) -> str:
    """Count the words in a piece of text."""
    return str(len(text.split()))

TOOLS = [
    {
        "name": "calculate",
        "description": (
            "Evaluate a basic arithmetic expression and return the numeric "
            "result as a string. Supports +, -, *, /, **, parentheses, and "
            "negative numbers. Use this any time the user asks for a "
            "calculation, even a simple one -- do not do math in your head."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "A valid arithmetic expression, e.g. '127 * 38' or '(12 + 4) / 2'.",
                }
            },
            "required": ["expression"],
        },
    },
    {
        "name": "count_words",
        "description": (
            "Count how many words are in a given piece of text and return "
            "the count as a string. Use this when the user asks for a word "
            "count of something rather than estimating it yourself."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to count words in.",
                }
            },
            "required": ["text"],
        },
    },
]

TOOL_FUNCTIONS = {
    "calculate": calculate,
    "count_words": count_words,
}

A couple of deliberate choices worth calling out. The calculate function uses Python's ast module to parse the expression into a syntax tree and walk it manually, rather than calling eval() directly — eval("import os; os.system(...)") is exactly the kind of thing you don't want an AI-controlled function anywhere near, even though ast.parse(mode="eval") would itself reject statements like import. The description fields are also longer than feels natural at first. That's intentional — Claude's tool selection quality depends heavily on how clearly each tool explains what it does and when to use it.

Step 2: The agent loop

This is the part that actually makes it "agentic." Save this as agent.py:

"""
The agent loop: send a message, check whether Claude wants to use a tool,
run that tool locally, send the result back, and repeat until Claude
gives a final text answer.
"""

from tools import TOOLS, TOOL_FUNCTIONS

def run_agent(client, user_message, model="claude-sonnet-4-6", max_iterations=5, verbose=True):
    messages = [{"role": "user", "content": user_message}]

    for step in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=1024,
            tools=TOOLS,
            messages=messages,
        )

        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return "".join(
                block.text for block in response.content if block.type == "text"
            )

        tool_results = []
        for block in response.content:
            if block.type == "text" and verbose and block.text.strip():
                print(f"  [Claude says]: {block.text.strip()}")

            if block.type == "tool_use":
                func = TOOL_FUNCTIONS.get(block.name)
                if verbose:
                    print(f"  [tool call]: {block.name}({block.input})")

                if func is None:
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": f"Unknown tool: {block.name}",
                        "is_error": True,
                    })
                    continue

                try:
                    result = func(**block.input)
                    if verbose:
                        print(f"  [tool result]: {result}")
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    })
                except Exception as exc:
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(exc),
                        "is_error": True,
                    })

        messages.append({"role": "user", "content": tool_results})

    return "Reached max_iterations without a final answer -- something is looping."

Three things in here are easy to get wrong, and the API will reject your request with a 400 error if you do:

The tool_result blocks have to go in a new user message, not appended to the assistant's message. The tool_result blocks must come first in that message's content array — any text from your side has to come after them. And every tool_use block in the assistant's response needs a matching tool_result with the same tool_use_id, including when a tool errors out — which is why even the error case still appends a tool_result, just with is_error: true.

Step 3: Test the loop before it ever calls the real API

Here's the part most tutorials skip, and it's the most useful part for actually trusting your code. The Claude API's tool-use responses have a documented, predictable shape — a stop_reason, and a content list of blocks that are either text or tool_use. So we can fake that shape, feed it to run_agent, and verify the loop, the tool dispatch, and the actual math/word-counting logic all work — without an API key, without spending a token.

Save this as test_agent_offline.py:

from types import SimpleNamespace
from agent import run_agent
from tools import calculate, count_words

def block(**kwargs):
    return SimpleNamespace(**kwargs)

class FakeMessages:
    def __init__(self, script):
        self.script = script
        self.calls = 0

    def create(self, **kwargs):
        response = self.script[self.calls]
        self.calls += 1
        return response

class FakeClient:
    def __init__(self, script):
        self.messages = FakeMessages(script)

def test_parallel_tool_calls():
    turn1 = SimpleNamespace(
        stop_reason="tool_use",
        content=[
            block(type="text", text="I'll do both of those."),
            block(type="tool_use", id="toolu_010", name="calculate",
                  input={"expression": "(12 + 4) / 2"}),
            block(type="tool_use", id="toolu_011", name="count_words",
                  input={"text": "the quick brown fox jumps over the lazy dog"}),
        ],
    )
    turn2 = SimpleNamespace(
        stop_reason="end_turn",
        content=[block(type="text", text="(12 + 4) / 2 is 8.0, and that sentence has 9 words.")],
    )

    client = FakeClient([turn1, turn2])
    answer = run_agent(client, "Two things for you...", verbose=True)

    assert "8.0" in answer
    assert "9 words" in answer
    print("test_parallel_tool_calls passed\n")

def test_underlying_functions_directly():
    assert calculate("127 * 38") == "4826"
    assert calculate("(12 + 4) / 2") == "8.0"
    assert calculate("-3 + 7 ** 2") == "46"
    assert count_words("the quick brown fox jumps over the lazy dog") == "9"

    try:
        calculate("import os")
        raise AssertionError("should have raised")
    except (ValueError, SyntaxError):
        pass

    print("test_underlying_functions_directly passed\n")

if __name__ == "__main__":
    test_underlying_functions_directly()
    test_parallel_tool_calls()
    print("All offline tests passed.")

Running this with python3 test_agent_offline.py produces:

test_underlying_functions_directly passed

  [Claude says]: I'll do both of those.
  [tool call]: calculate({'expression': '(12 + 4) / 2'})
  [tool result]: 8.0
  [tool call]: count_words({'text': 'the quick brown fox jumps over the lazy dog'})
  [tool result]: 9
test_parallel_tool_calls passed

All offline tests passed.

That output is from actually running the code above — not a transcript I wrote by hand. It confirms three things at once: the calculator handles operator precedence and negative numbers correctly, the agent loop correctly processes multiple tool calls in a single turn (Claude often does both calculations in parallel rather than one at a time), and the message history gets built in the shape the real API expects.

If you change anything — add a tool, change a schema, rewrite the loop — rerun this file first. It catches the majority of "why did my agent just 400" problems in seconds, with zero API cost.

Step 4: Run it for real

Once the offline tests pass, swap in the real client. Save this as run.py:

"""
Run with a real API key:

    export ANTHROPIC_API_KEY="sk-ant-..."
    pip install anthropic
    python3 run.py
"""

from anthropic import Anthropic
from agent import run_agent

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

if __name__ == "__main__":
    question = (
        "What's 127 * 38, and how many words are in the sentence "
        "'the quick brown fox jumps over the lazy dog'?"
    )
    answer = run_agent(client, question)
    print("\nFinal answer:", answer)

Set your API key as an environment variable, install the SDK, and run it:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"
pip install anthropic
python3 run.py

Because the offline test already exercised the exact same run_agent function with a response shaped the way the real API responds, what you're really testing here is just "does my API key work and does the real model behave the way the documented shape says it will" — which is a much smaller, cheaper thing to debug.

What's actually happening, step by step

For the question above, here's the real sequence:

Claude receives the question along with the two tool definitions. It decides this needs both tools, and — because Claude 4-generation models default to parallel tool calling — it can return both tool_use blocks in a single response, often with a short sentence of context first ("I'll calculate that and count the words for you").

Our loop sees stop_reason == "tool_use", runs calculate("127 * 38") and count_words(...) locally, and sends both results back in a single new user message, with the tool_result blocks first.

Claude receives those results and, now having everything it needs, responds with stop_reason == "end_turn" and a plain text answer. Our loop sees that and returns the text. Done — two API calls total, with real computation happening in real Python in between.

Things to watch out for as you extend this

Pick the right model for the job. Anthropic's own guidance is to use a larger model like Opus for tools with ambiguous inputs or many options, and a smaller model like Haiku for simple, well-defined tools — smaller models are more likely to guess at missing parameters rather than asking.

Don't skip max_iterations. If a tool's result regularly causes Claude to call the same tool again, you can end up in a loop. The cap in run_agent is a blunt but effective safety net while you're developing.

Tool descriptions are most of the work. If Claude picks the wrong tool, or the right tool with weird arguments, the fix is almost always a clearer description — what the tool does, when to use it, when not to, and what each parameter means — rather than a change to your loop logic.

For anything beyond a toy, look at the SDK's tool runner. Once you're comfortable with the manual loop above (and understand why it's shaped the way it is), Anthropic's Python, TypeScript, and Ruby SDKs include a beta "tool runner" that handles the request/response cycle and conversation state for you. It's worth learning the manual version first — it's what the tool runner is doing under the hood, and it's much easier to debug when something goes wrong.