how to build Claude AI agent for VPS

Wetin e mean to build agent with Claude

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

This split na why e sweet. You go get frontier-level reasoning without you need to operate model, and you go get full control of wetin agent fit touch, because the tools dey run for hardware wey you own. If you don already build first Claude program, the first Claude app on a VPS guide go 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 dey go so and the list of tools wey agent fit use; Claude go send back its next message. That message na either final answer or request to call tool. For the build-it-yourself path, no separate "agent API": tool use na feature of this single endpoint, and the loop around am na yours to run.

Claude na stateless between calls, wey mean say e no dey remember anything on its own. Each request carry the whole conversation. Your code dey hold the history and dey send am every turn, na why each turn in a long session cost more tokens than the last. No be limitation, na design choice: because state dey live for your server, you decide exactly wetin Claude go see, and nothing about the task dey store anywhere wey you no control.

Tool use na the agent loop

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

You fit write that loop by hand with few lines, and many people dey do am, because e easy to see and easy to control. The official SDKs also provide tool runner wey go drive the loop for you: you go supply the tool functions, and the SDK go handle the back-and-forth of calling Claude, running your tools, and feeding the results back until Claude finish. Either way, the shape na the same. The runner just dey save you from writing the loop yourself.

Three ways to build, and which fit a VPS

Dem get three ways to build Claude agent, and dem differ for how much machinery you go run.

The first one na your own code dey call Claude API with your own tools. You go write the loop, or use the SDK's tool runner, and you go host the whole thing for your VPS. This na the common choice, because e give you complete control over tools, data, and security, and e dey run as ordinary program for your server. Most of this guide dey assume this path.

The second one na the Claude Agent SDK. This na Claude Code, the coding agent, wey dem package as library wey you fit build on. E come with full agent loop and built-in tools for reading and writing files, running shell commands, and searching, so you no need to assemble dem from scratch. E also dey run for your own server, wey make e fit well for VPS if you want capable file-and-shell agent without you need to build the harness yourself. Agent wey dey read files and run shell commands need containment before e fit work unattended, and running Claude Code safely on a server go cover the permission system, the sandbox, and the isolation options.

The third one na Managed Agents, where Anthropic dey run the loop and host sandbox wey agent tools dey run for. This na the hands-off option: e get far less wey you need to operate, but agent workspace dey live for Anthropic infrastructure instead of your VPS. Use am when you want least operational work and you no need tools to run for your own machine. For the other two, your server na the home of the agent, wey na wetin the rest of this guide dey talk about.

Connecting tools with MCP

Whichever path you choose, you go want connect agent to real systems, and Model Context Protocol na the tidy way to do am. MCP na open standard for exposing tools and data to agent. Instead of you to hand-code integration for every service, you go point Claude to MCP server wey don already present those capabilities as tools. You fit run MCP servers as small services for the same VPS, each with only the access wey e need, wey I go cover for running MCP servers on a VPS.

Choosing a model

Claude come with several models, and to pick one na trade between capability, speed, and cost. As we dey write this, the mainstream choices 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 close to Opus for many tasks; and Claude Haiku 4.5 (claude-haiku-4-5), the fastest and cheapest, 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, no add date to am.

One practical pattern na to mix dem. Let cheaper model handle routine tool calls and stronger one handle the hard decisions. Because model na just string for your request, to switch na one-line change, so start with capable default and tune downward where speed or cost matter pass the last bit of quality.

Run am as a hardened service on your VPS

Agent only useful if e dey run, and e only safe if e dey contained. For VPS, both of dem dey come from running agent as a hardened system service instead of program wey you start by hand for terminal. As a service, e go start for boot, restart if e crash, and log to the journal. As a hardened service, e go run as unprivileged user with only the access wey e need, so bug or bad instruction no go get ceiling.

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

Then finish the server itself. Put SSH on keys only and lock down the account wey you dey administer from, as in SSH hardening on a VPS. If you prefer to drive agent from interactive session while you dey build am, running Claude Code on a VPS with tmux na good companion. And if you want the concepts behind all of this, without tying dem to one model, the sister guide on building your own AI agent on a VPS go lay out the foundations.

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

FAQ

Which Claude model should I use to build an agent?

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

Do I run the whole agent on my VPS, or does Anthropic?

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

What is the difference between the Claude API and the Claude Agent SDK?

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

How do I keep my Claude API key safe on a server?

Keep am server-side and out of your code. Store am for file wey only the account wey agent dey run as fit read, load am into 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 ever reach user device, wey na wetin make agent wey run for server easier to secure than one wey dey inside client app.

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

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