How to Build Claude AI Agent for VPS

Wetin building an agent with Claude mean

Building an agent with Claude mean say you dey use Claude as the reasoning core, while the loop, tools, and data dey for your own server. Claude go decide wetin to do; your VPS go carry am out. You go send the task and current state give Claude. Claude go reply with either answer or request to use one of your tools. Your code go run the tool and send the result back. The loop go continue until the job finish. The intelligence na service wey you dey call through internet. Everything around am na your own.

Na this separation make the setup useful. You get frontier-level reasoning without operating a model, and you keep full control of wetin the agent fit access, because the tools dey run for hardware wey you own. If you don already build your first Claude program, the guide for first Claude app on a VPS dey cover the groundwork wey this one dey build on.

Claude na the brain: the Messages API

Every call to Claude dey pass through one endpoint, the Messages API. You go send the conversation wey don happen and the list of tools wey the agent fit use; Claude go send back the next message. That message fit be final answer or request to call a tool. For the build-it-yourself path, no separate "agent API" dey: tool use na feature of this single endpoint, and na you go run the loop around am.

Claude no dey keep state between calls, so e no remember anything by itself. Every request carry the complete conversation. Your code hold the history and send am for every turn, and na why each turn for long session dey cost more tokens pass the previous one. This no really be limitation; na design choice. Because your server hold the state, na you decide exactly wetin Claude go see, and nothing about the task dey stored for anywhere wey you no control. But e mean say the prompt dey grow continuously. Claude's context window fit handle this without wahala, but local model for the same loop no fit. Na why Ollama need make you raise num_ctx before e stop truncating long prompts.

Tool use na agent loop

Agent loop wey use Claude no hard to explain. You go send request wey include your tools. Claude go read the task and, if e need act, e go reply with tool-use request wey name one tool and fill the inputs. Your code go run that tool, then send the result back to Claude for the next request. Claude go read the result and either ask for another tool or write the final reply. Once e stop asking for tools, the task don finish.

You fit write that loop by hand with just few lines, and plenty people dey do am because e easy to see and control. The official SDKs also get tool runner wey dey drive the loop for you: you provide the tool functions, and the SDK handle the back-and-forth of calling Claude, running your tools, and sending the results back until Claude finish. Either way, the structure remain the same. The runner only save you from writing the loop yourself. If the loop still dey look abstract, write one minimal loop before you use runner. Na this step everything else depend on for this staged path for learning AI agents from scratch.

Ways three dey to build am, and which one fit VPS

Ways three dey to build Claude agent, and the difference na how much of the machinery you go run.

The first one na your own code wey dey call Claude API with your own tools. You write the loop, or use the SDK's tool runner, then host everything for your VPS. Na this one people dey commonly choose because e give you complete control over the tools, data, and security. E dey run like normal program for your server. Most part of this guide assume say na this path you dey use.

The second one na Claude Agent SDK. Na Claude Code, the coding agent, package as library wey you fit build on. E ship with complete agent loop and built-in tools for reading and writing files, running shell commands, and searching. So you no need assemble those things from scratch. E still dey run for your own server, so e fit VPS well when you want capable file-and-shell agent but you no want build the harness by yourself. Agent wey dey read files and run shell commands need containment before e fit work unattended. Running Claude Code safely for server explain the permission system, sandbox, and isolation options.

The third one na Managed Agents, where Anthropic dey run the loop and host sandbox wey the agent tools dey execute inside. Na the option wey need the least hands-on work. But the agent workspace dey for Anthropic infrastructure, no be your VPS. Use am when you want reduce operational work and you no need the tools to run for your own machine. For the other two options, na your server be the agent home. Na that one the rest of this guide dey explain.

Tools connect with MCP

Any path wey you choose, you go want connect the agent to real systems, and Model Context Protocol na the neat way to do am. MCP na open standard for exposing tools and data to an agent. Instead make you write integration code by hand for every service, you point Claude to MCP server wey already presents those capabilities as tools. You fit run MCP servers as small services for the same VPS, with each one getting only the access wey e need. I explain this for how to run MCP servers for a VPS.

Model wey you go choose

Claude get different models, and choosing one na trade-off between capability, speed, and cost. As of now, the common options na Claude Opus 4.8 (claude-opus-4-8), the capable default for hard reasoning and long agent runs; Claude Sonnet 5 (claude-sonnet-5), a balanced option wey cheaper and faster while e still dey close to Opus for many tasks; and Claude Haiku 4.5 (claude-haiku-4-5), the fastest and cheapest option for simple, high-volume steps. Above dem dey Claude Fable 5 (claude-fable-5), the most capable model, for the most demanding work. Use the exact model identifier for your code, and no add date to am.

One practical pattern na to mix dem. Make cheaper model handle routine tool calls, while stronger one handle hard decisions. Because model na just string for your request, switching am na one-line change. So start with a capable default, then tune am downward where speed or cost matter pass the last small improvement for quality.

Run am as hardened service for your VPS

Agent dey useful only if e stay dey run, and e dey safe only if you contain am. For VPS, you fit achieve both by running agent as hardened system service instead of program wey you start by hand for terminal. As service, e go start when system boot, restart if e crash, and write logs to journal. When you harden am, e go run as unprivileged user with only the access wey e need. So if bug or bad instruction happen, the damage go get limit. Service unit fit only limit wetin process fit touch. The remaining protection suppose dey inside agent harness itself. Na the work wey the DeepSeek Harness plugins wey worth installing dey do for another stack: spend caps, per-tool permission rules, and prompt-injection scanning.

The most important rule na to keep your Claude API key for server side. The key dey pay for and authorise every call, so put am for file wey only agent user fit read. Load am into service as environment variable. Never put am for code, repository, or anywhere browser fit reach. Generate complete, hardened service unit for your agent here:

Then complete the server setup. Configure SSH to use keys only, and lock down the account wey you dey use to administer am, as e dey explained for SSH hardening on a VPS. If you prefer to control agent from interactive session while you dey build am, running Claude Code on a VPS with tmux na good companion. After you open second session for the same machine, the two fit pass work between themselves instead of you carrying every instruction from one pane go the other. If you want understand the concepts behind all this without tying dem to one model, the sister guide on building your own AI agent on a VPS explain the foundations.

If terminal coding assistant na wetin you want, running a coding AI agent on a VPS cover Aider and Goose.

FAQ

Which Claude model I suppose use to build an agent?

Start with Claude Opus 4.8 (claude-opus-4-8), wey be the capable default, then adjust from there. Claude Sonnet 5 (claude-sonnet-5) cheaper and faster for most work, Claude Haiku 4.5 (claude-haiku-4-5) best for simple high-volume steps, and Claude Fable 5 (claude-fable-5) get the highest capability for the hardest tasks. Common pattern na to use cheaper model for routine steps and stronger one for hard decisions, because switching na one-line change.

I go run the whole agent for my VPS, or Anthropic go run am?

E depend on the approach. If you write your own loop against the Claude API, or use the Claude Agent SDK, the agent go run entirely for your VPS and na only the model calls go Anthropic. If you use Managed Agents, Anthropic go run the loop and host the sandbox where tools dey execute, so less of am dey live for your server. For agent wey go run for your own machine, use one of the first two.

Wetin be the difference between Claude API and Claude Agent SDK?

Claude API na the raw Messages endpoint: you send conversation and tools, then write the agent loop around am, or use SDK tool runner to drive am. Claude Agent SDK na higher-level library, Claude Code packaged for building on, wey ships full loop and built-in file, shell, and search tools. Use API when you want define everything by yourself, and Agent SDK when you want capable agent without assembling the harness.

How I fit keep my Claude API key safe for server?

Keep am server-side and comot am from your code. Store am for file wey only the account wey agent dey run as fit read, load am into the service as environment variable, and never commit am to repository or expose am to browser. Because every request to Claude dey come from your server, the key no need reach user's device. Na this make server-run agent easier to secure than one wey you embed inside client app.

I need self-host model to build agent with Claude?

No. With Claude, the model na hosted service wey you call through API, so nothing dey run for GPU. Your VPS dey run agent loop, tools, and data, while the reasoning dey happen for Anthropic side. Na this dey allow modest server run capable agent. If you want fully local model instead, na the self-hosted path wey companion guide on building your own AI agent cover.