Run Claude Code & Codex on a cloud VPS

Provision a VPS

Start with Ubuntu 22.04+ and at least 2 GB RAM (4 GB+ recommended for large repos and heavy builds). Both CLIs run on Node.js 22, so install a current LTS from NodeSource:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl

# Install Node.js 22 LTS via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version   # v22.x.x
npm --version

Install Claude Code

Install Anthropic's Claude Code globally with npm, then authenticate by exporting your ANTHROPIC_API_KEY. Run the claude command from inside the project directory you want it to work on:

npm install -g @anthropic-ai/claude-code

# Authenticate (BYO Anthropic key)
export ANTHROPIC_API_KEY="sk-ant-..."

# Run it inside your project directory
cd ~/my-project
claude

Claude Code operates on the working directory you launch it in — it reads the files there, proposes edits, and runs commands with your confirmation.

Install Codex

OpenAI's Codex CLI installs the same way. Set your OPENAI_API_KEY, then run codex from your repo:

npm install -g @openai/codex

# Authenticate (BYO OpenAI key)
export OPENAI_API_KEY="sk-..."

# Run it inside your project directory
cd ~/my-project
codex

Use it from anywhere

SSH into the box from any laptop, desktop, or even a tablet, then launch either CLI:

ssh user@your-server
cd ~/my-project
claude      # or: codex

Because the agent runs on the server, a long task keeps going even if your connection drops. Wrap it in a tmux session (or use the AgentOcean web terminal) so you can detach and reattach without interrupting the run:

# Start a persistent session
tmux new -s code
claude

# Detach with Ctrl-b then d — the agent keeps running.
# Reattach later from any device:
tmux attach -t code

Keep your keys safe

Both tools are BYOK (Bring Your Own Key). Set the keys as environment variables so every shell session picks them up — add them to ~/.bashrc, or keep them in a .env file and source it. Never commit keys to a repo:

# Append to ~/.bashrc so keys load on every login
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
echo 'export OPENAI_API_KEY="sk-..."'        >> ~/.bashrc
source ~/.bashrc

# Or keep them in a .env (and add .env to .gitignore)
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...

Your keys live on your own server and are billed against your Anthropic or OpenAI account — they never pass through AgentOcean.

Troubleshooting — what actually goes wrong

We install both CLIs on fresh, disposable VPS instances continuously to test our own provisioning, and the install itself is the reliable part — npm install -g on a clean Ubuntu box with Node 22 has not failed for us. Everything that does go wrong sits on either side of it: the Node version underneath, or the API account behind the key.

It installed, and it still cannot answer

A successful npm install -g means npm fetched a package. It says nothing about whether your key works, has credit, or is allowed to use the model the CLI asks for — those fail on the first real request, not at install time, and they are the failures we hit most. Verify the key on its own before blaming the tool:

# Anthropic — a minimal request that costs a fraction of a cent
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-5","max_tokens":16,
       "messages":[{"role":"user","content":"say ready"}]}'

# OpenAI
curl -s https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-4o","max_tokens":16,
       "messages":[{"role":"user","content":"say ready"}]}'

A 401 is the key itself — wrong value, or revoked. A 404 on the model name usually means your account cannot reach that model rather than that the model is gone. A 429 is rate limiting or an exhausted balance, and it is the one people misread as a broken install. Billing and quota errors surface as HTTP failures on first use, and no amount of reinstalling changes them — one of our own agent runs failed every single prompt purely because the key behind it had hit its spend cap.

Model names go stale faster than guides do

Both CLIs let you pin a model, and model identifiers are retired and replaced regularly — a string copied from a blog post six months old will often 404 today. Take the identifier from the provider's own current model list rather than from any guide, including this one. If a CLI that worked last month suddenly cannot reach a model, check that before anything else.

Wrong Node, or the command is not found after install

Both CLIs need a current Node. If you installed Node from Ubuntu's own repositories rather than NodeSource, you may be on a much older major version, and the failure shows up as a syntax error inside the package rather than as a clear “unsupported version” message. And if npm install -g succeeded but the command is not found, the global bin directory is not on your PATH — which is also why installing with sudo and then running as your own user often appears to do nothing:

node --version          # expect v22.x
npm root -g             # where global packages actually landed
npm bin -g              # this must be on your PATH
which claude codex      # empty output means PATH, not a failed install

Treat the key as the thing worth protecting

An API key on a VPS is a spending credential sitting on a machine exposed to the internet, which is a different risk profile from the same key on your laptop. Keep it out of shell history and out of the repo, follow the VPS security guide for SSH keys and the firewall, and be aware of one trap that guide documents in detail: if you also run anything in Docker on this box, a published container port is reachable from the internet even when UFW says it is denied. We measured a database container going from unreachable to publicly open the moment it started, with no firewall rule changed.

Related

• How to self-host Hermes Agent on a VPS
• Secure your VPS: firewall, SSH keys & fail2ban
• AI agent use cases — what you can automate