Last Updated: March 8, 2026
I run Claude Code on a $5 Hostinger VPS. It handles my Telegram messages, manages my calendar, processes email, and runs multi-agent board meetings. All day, every day.
Authentication was the hardest part to get right. Not because the rules are complicated. They are not. But because the tooling for headless servers is still rough, and the documentation has gaps. This guide covers every authentication method I tested, what actually works on a server, and the hybrid architecture I settled on after months of iteration.
The Problem with OAuth on Servers
Claude Code’s default login opens a browser. Your VPS does not have one.
You run claude /login on your server and get a URL you cannot reach. Or the token refreshes fine for fifteen hours, then expires overnight. Your bot stops responding. You wake up to a dead system and a vague error.
This is not hypothetical. GitHub issue #28827 documents headless refresh failures. Issue #7100, requesting proper headless authentication, was closed as NOT_PLANNED. Issue #21678 reports Cloudflare blocking entire Hetzner datacenter IP ranges.
The workarounds exist. SSH port forwarding can redirect the browser auth to your local machine. Copying auth.json between machines works until the token expires. None of these are production-grade.
The actual solution depends on what you are building. I built a Telegram AI assistant called GoBot. It runs 24/7 with voice messages, calendar management, email processing, and multi-agent board meetings. Every authentication decision in this guide comes from running that system in production for months.
Four Authentication Methods That Work on Servers
Claude Code supports multiple authentication paths. Here is how they compare for server use.
| Method | Billing | Token Expiry | Best For |
|---|---|---|---|
API Key (ANTHROPIC_API_KEY) |
Pay-per-token | Never | Production bots, automation, Agent SDK |
| Claude Code CLI with subscription | Pro/Max plan | ~15 hours | Interactive dev sessions via SSH |
| Cloud Providers (Bedrock/Vertex/Foundry) | Cloud billing | Varies | Enterprise environments |
apiKeyHelper script |
Varies | Custom TTL | Key rotation, vault integration |
For most people building an AI assistant that runs 24/7, API keys are the right choice. They never expire. They do not need a browser. One environment variable and your server authenticates forever.
API Keys: The Production Standard
Generate a key at console.anthropic.com. Set it on your server:
export ANTHROPIC_API_KEY="sk-ant-..."Add this to your shell profile, systemd service file, or .env for persistence. Claude Code picks it up automatically.
API keys use pay-per-token billing through the Anthropic Console. This is separate from any Pro or Max subscription. The billing runs under Commercial Terms, not Consumer Terms. Different legal framework, different rules.
Anthropic explicitly recommends API keys for programmatic use. Their Legal and Compliance page states: “Developers building products or services that interact with Claude’s capabilities, including those using the Agent SDK, should use API key authentication through Claude Console or a supported cloud provider” (source).
There is one known bug worth noting. In interactive mode, Claude Code sometimes ignores the API key and demands OAuth login. Issue #27900 documents this. The workaround: set ANTHROPIC_AUTH_TOKEN=dummy alongside your API key.
The Cost Question
API keys bill per token. Subscriptions bill flat monthly. Which costs less depends on your usage pattern.
| Usage Level | Max Subscription | API Cost (estimated) | Better Value |
|---|---|---|---|
| Light (1-2 hours/day) | $100/mo (Max 5x) | $30-80/mo | API Key |
| Moderate (3-5 hours/day) | $200/mo (Max 20x) | $100-360/mo | Subscription |
| Heavy (8+ hours or automation) | $200/mo (Max 20x) | $500-1,500/mo | Subscription |
Most developers spend under $12 per day on API usage, according to a cost analysis by ShareUHack. But costs scale fast with heavy agentic workloads. An HN commenter noted: “In a month of Claude Code, it is easy to use so many tokens that it would have exceeded $1,000 if charged via the API.”
You can bring API costs down significantly. Prompt caching saves up to 90% on repeated context. The Batch API offers a 50% discount for non-urgent tasks. Smart model routing between Haiku ($1 per million input tokens), Sonnet ($3), and Opus ($15) makes the biggest difference. See Anthropic’s pricing page for current rates.
GoBot uses all three tiers. Haiku handles roughly 60% of messages. Sonnet covers 30%. Opus only fires for complex analysis. The free Telegram Bot Course walks through this model routing setup step by step.
My Setup: Hybrid Architecture
After months of testing, I settled on a hybrid approach. Two machines, two authentication methods, one system.
Telegram message arrives
→ VPS (always on, webhook)
→ Mac awake? Forward to Mac
Mac runs claude -p (subscription billing, $0 per message)
Full MCP server access (Gmail, Calendar, Notion, etc.)
→ Mac asleep? Process on VPS
Simple queries → Haiku via API ($0.01-0.05)
Complex tasks → Sonnet/Opus via API ($0.10-2.00)The VPS catches every message 24/7. It checks if my Mac is awake via a health endpoint. When the Mac is online, messages get forwarded for processing with Claude Code CLI using my Max subscription. No per-token charges. Full access to all MCP servers.
When the Mac is asleep, the VPS handles messages directly using API keys. Smart model routing keeps costs low. Haiku handles roughly 60% of messages. Sonnet covers 30%. Opus only fires for complex analysis, maybe 10% of requests. A daily budget cap with auto-downgrade prevents surprises.
This is not a multi-user service. It is a personal AI assistant called GoBot. One Telegram user. One ALLOWED_USER_ID that blocks everyone else. Your data stays on your server. Your API keys stay in your environment. Each person in the Autonomee community builds their own GoBot instance on their own infrastructure.
What Anthropic Actually Allows on Servers
Running Claude Code on a remote server is permitted. There are no location restrictions in the Terms of Service. Anthropic documents GitHub Actions and GitLab CI/CD integration for programmatic use, and their authentication page supports API keys that work on any machine.
The critical distinction is between the tool and the authentication method.
Using the Claude Code binary (claude -p) on your server: permitted. It is Anthropic’s own product. Using your subscription OAuth tokens in a different tool that is not Claude Code: prohibited. The Legal and Compliance page is explicit: “OAuth authentication is intended exclusively for Claude Code and Claude.ai” (source).
Consumer Terms Section 3 prohibits accessing services “through automated or non-human means, whether through a bot, script, or otherwise” except via API Key or where Anthropic explicitly permits it. Claude Code CLI is that explicit permission. It is built for scripted and automated use (source).
For the full legal breakdown with every relevant section analyzed, read my Claude Code Terms of Service Explained guide.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| “OAuth account information not found” | Token expired (~15h) | Use API key for server workloads |
| Browser will not open | No display server on VPS | Use API key or SSH port forwarding for one-time setup |
| “This organization has been disabled” | Account flagged | Check Console billing, then appeal guide |
| Claude Code ignores API key in interactive mode | Bug #27900 | Set ANTHROPIC_AUTH_TOKEN=dummy |
| Cloudflare blocking VPS IP | Datacenter IP flagged (#21678) | Try different datacenter region |
| Concurrent session auth conflicts | Refresh token race (#24317) | Use separate API keys per process |
Getting Started
The simplest path: set ANTHROPIC_API_KEY on your server and start building. You can always add hybrid routing later.
The free Telegram Bot Course walks through the full setup. From first install to a running AI assistant with memory, voice, and background services. 366+ professionals in the Autonomee community have built theirs. Some connect Claude Code to Google Chat, Microsoft Teams, Discord, WhatsApp, and Slack.
For the advanced hybrid architecture with model routing, multi-agent board meetings, and 25+ features, that is what we build together inside Autonomee.
Frequently Asked Questions
Can I run Claude Code on a VPS or remote server?
Yes. Anthropic has no location restrictions in their Terms of Service. Their authentication docs support API keys that work on any machine, and they document CI/CD integration with GitHub Actions and GitLab CI/CD. Authenticate with API keys for production workloads.
Does running Claude Code on a server violate Anthropic’s Terms of Service?
Running the official Claude Code binary on a server does not violate the terms. What violates them is extracting your subscription OAuth tokens for use in third-party tools. The binary itself has no restrictions on where it runs. See my full ToS breakdown for the specific sections.
Should I use API keys or my Max subscription on a server?
For always-on bots and automation, API keys are the recommended approach. They never expire and Anthropic explicitly directs developers to use them for programmatic access. For interactive SSH development sessions, your subscription works fine. The hybrid approach combines both for optimal cost and reliability. GoBot uses exactly this setup, and the free Telegram Bot Course covers the full configuration.
How much does running Claude Code with API keys cost per month?
Most developers spend $30 to $360 per month depending on usage intensity. Smart model routing between Haiku, Sonnet, and Opus reduces costs significantly. Haiku handles simple queries for roughly $0.01 each. Prompt caching saves up to 90% on repeated context. A daily budget cap prevents surprises.
What happens if authentication breaks while a task is running?
OAuth token expiry mid-task kills the session without completing it. GitHub issue #12447 documents this for autonomous workflows. API keys do not have this problem. For anything critical, always use API keys.
