Build an AI agent with Claude on a VPS

What building an agent with Claude means

Building an agent with Claude means using Claude as the reasoning core while the loop, the tools, and the data live on your own server. Claude decides what to do; your VPS carries it out. You send Claude the task and the current state, Claude replies with either an answer or a request to use one of your tools, your code runs the tool and sends the result back, and the loop continues until the job is done. The intelligence is a service you call over the internet. Everything around it is yours.

This split is the appeal. You get frontier-level reasoning without operating a model, and you keep full control of what the agent can touch, because the tools run on hardware you own. If you have already built a first Claude program, the first Claude app on a VPS guide covers the groundwork this one builds on.

Claude is the brain: the Messages API

Every call to Claude goes through one endpoint, the Messages API. You send the conversation so far and the list of tools the agent may use; Claude sends back its next message. That message is either a final answer or a request to call a tool. For the build-it-yourself path there is no separate "agent API": tool use is a feature of this single endpoint, and the loop around it is yours to run.

Claude is stateless between calls, which means it remembers nothing on its own. Each request carries the whole conversation. Your code holds the history and sends it every turn. That is not a limitation so much as a design choice: because the state lives on your server, you decide exactly what Claude sees, and nothing about the task is stored anywhere you do not control.

Tool use is the agent loop

The agent loop with Claude is simple to describe. You send a request that includes your tools. Claude reads the task and, if it needs to act, replies with a tool-use request that names a tool and fills in its inputs. Your code runs that tool, then sends the result back to Claude in the next request. Claude reads the result and either asks for another tool or writes its final reply. When it stops asking for tools, the task is done.

You can write that loop by hand in a few lines, and many people do, because it is easy to see and easy to control. The official SDKs also provide a tool runner that drives the loop for you: you supply the tool functions, and the SDK handles the back-and-forth of calling Claude, running your tools, and feeding the results back until Claude is finished. Either way the shape is the same. The runner just saves you from writing the loop yourself.

Three ways to build, and which fit a VPS

There are three ways to build a Claude agent, and they differ in how much of the machinery you run.

The first is your own code calling the Claude API with your own tools. You write the loop, or use the SDK's tool runner, and you host the whole thing on your VPS. This is the common choice, because it gives you complete control over the tools, the data, and the security, and it runs as an ordinary program on your server. Most of this guide assumes this path.

The second is the Claude Agent SDK. This is Claude Code, the coding agent, packaged as a library you can build on. It ships a full agent loop and built-in tools for reading and writing files, running shell commands, and searching, so you do not assemble those from scratch. It also runs on your own server, which makes it a strong fit for a VPS when you want a capable file-and-shell agent without building the harness yourself.

The third is Managed Agents, where Anthropic runs the loop and hosts a sandbox in which the agent's tools execute. This is the hands-off option: there is far less for you to operate, but the agent's workspace lives on Anthropic's infrastructure rather than your VPS. Reach for it when you want the least operational work and do not need the tools to run on your own machine. For the other two, your server is the home of the agent, which is what the rest of this guide is about.

Connecting tools with MCP

Whichever path you choose, you will want to connect the agent to real systems, and the Model Context Protocol is the tidy way to do it. MCP is an open standard for exposing tools and data to an agent. Rather than hand-code an integration for every service, you point Claude at an MCP server that already presents those capabilities as tools. You can run MCP servers as small services on the same VPS, each with only the access it needs, which I cover in running MCP servers on a VPS.

Choosing a model

Claude comes in several models, and picking one is a trade between capability, speed, and cost. As of this writing the mainstream choices are 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 that is cheaper and quicker while staying close to Opus on many tasks; and Claude Haiku 4.5 (claude-haiku-4-5), the fastest and cheapest, for simple, high-volume steps. Above them sits Claude Fable 5 (claude-fable-5), the most capable model, for the most demanding work. Use the exact model identifier in your code, with no date added to it.

A practical pattern is to mix them. Let a cheaper model handle routine tool calls and a stronger one handle the hard decisions. Because the model is just a string in your request, switching is a one-line change, so start with a capable default and tune downward where speed or cost matters more than the last bit of quality.

Run it as a hardened service on your VPS

An agent is only useful if it stays running, and it is only safe if it is contained. On a VPS both of those come from running the agent as a hardened system service rather than a program you started by hand in a terminal. As a service it starts on boot, restarts if it crashes, and logs to the journal. Hardened, it runs as an unprivileged user with only the access it needs, so a bug or a bad instruction has a ceiling.

The single most important rule is to keep your Claude API key server-side. The key pays for and authorises every call, so it belongs in a file readable only by the agent's user, loaded into the service as an environment variable, and never placed in code, in a repository, or anywhere a browser could reach. Generate a complete, hardened service unit for your agent here:

Then finish the server itself. Put SSH on keys only and lock down the account you administer from, as in SSH hardening on a VPS. If you would rather drive the agent from an interactive session while you build it, running Claude Code on a VPS with tmux is a good companion. And if you want the concepts behind all of this, without tying them to one model, the sister guide on building your own AI agent on a VPS lays out the foundations.

If a terminal coding assistant is what you want, running a coding AI agent on a VPS covers 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) is cheaper and faster for most work, Claude Haiku 4.5 (claude-haiku-4-5) is best for simple high-volume steps, and Claude Fable 5 (claude-fable-5) is the most capable for the hardest tasks. A common pattern is to use a cheaper model for routine steps and a stronger one for the hard decisions, since switching is a one-line change.

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

It depends on the approach. If you write your own loop against the Claude API, or use the Claude Agent SDK, the agent runs entirely on your VPS and only the model calls go out to Anthropic. If you use Managed Agents, Anthropic runs the loop and hosts the sandbox where tools execute, so less of it lives on your server. For an agent that runs on 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 is the raw Messages endpoint: you send a conversation and tools, and you write the agent loop around it, or use the SDK's tool runner to drive it. The Claude Agent SDK is a higher-level library, Claude Code packaged for building on, that ships a full loop and built-in file, shell, and search tools. Use the API when you want to define everything yourself, and the Agent SDK when you want a capable agent without assembling the harness.

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

Keep it server-side and out of your code. Store it in a file readable only by the account the agent runs as, load it into the service as an environment variable, and never commit it to a repository or expose it to a browser. Because every request to Claude goes from your server, the key never needs to reach a user's device, which is what makes a server-run agent easier to secure than one embedded in a client app.

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

No. With Claude the model is a hosted service you call over the API, so there is nothing to run on a GPU. Your VPS runs the agent loop, the tools, and the data, and the reasoning happens on Anthropic's side. That is what lets a modest server run a capable agent. If you want a fully local model instead, that is the self-hosted path covered in the companion guide on building your own AI agent.