Claude Code on a remote server over SSH: install, API key and tmux

Running Claude Code on a server over SSH makes sense when the project lives on a remote machine: a dev server with data, a powerful build box, a headless VPS. Claude Code is a terminal agent, so an SSH connection is all it needs. Below are the install steps from the official docs (the Advanced setup page), key-based authentication with no browser, working in tmux, and protecting the key.

Server requirements

According to the docs, Claude Code supports Ubuntu 20.04+, Debian 10+ and Alpine Linux 3.19+. You need at least 4 GB RAM, an x64 or ARM64 CPU, and internet access. The official installer doesn't need Node.js; it installs a native binary.

Installing Claude Code on the server

Connect over SSH as a regular user, not root, and run:

curl -fsSL https://claude.ai/install.sh | bash

The installer puts the claude command in ~/.local/bin. If your shell can't find it, add the directory to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Check the install:

claude --version
claude doctor

The command is claude. There is no separate claude-code binary.

There are alternatives. Anthropic publishes signed apt, dnf and apk repositories for Debian/Ubuntu, Fedora/RHEL and Alpine (see the Install with Linux package managers section of the docs). If Node.js is already on the server, npm install -g @anthropic-ai/claude-code works too, without sudo. The official installer's build updates itself; package-manager builds update with the rest of the system.

Authenticating with a Zukko key, no browser

A server usually has no browser for account login, and you don't need one. If ANTHROPIC_AUTH_TOKEN is set, Claude Code uses it. Per the docs it ranks above subscription login and is sent as an Authorization: Bearer header.

Add to ~/.bashrc:

export ANTHROPIC_BASE_URL="https://api.zukko.pro"
export ANTHROPIC_AUTH_TOKEN="fetch_your_key"
export ANTHROPIC_MODEL="claude-sonnet-5"

No /v1 in the base URL; Claude Code adds it. The other option is the env block in ~/.claude/settings.json, which keeps the variables visible to Claude Code only:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zukko.pro",
    "ANTHROPIC_AUTH_TOKEN": "fetch_your_key",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}

Lock the file down from other users on the server: chmod 600 ~/.claude/settings.json (or ~/.bashrc). Claude Code does not read a .env file in the project folder on its own, so putting the key there won't help.

Check the connection and list models:

curl -s https://api.zukko.pro/v1/models -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

The detailed guide is in the Zukko Claude Code docs↗.

Working with Claude Code on the server

Go to the project folder and start an interactive session:

cd /var/www/myapp
claude

Then describe tasks in plain language: "find where API errors are handled and add logging", "why does this test fail". Claude Code has no special subcommands like analyze or edit. The agent reads files, proposes edits, and runs commands itself, asking for permission.

For one-off tasks without interaction, use -p:

claude -p "Summarize what changed in the last 5 commits" --allowedTools "Bash(git log *),Bash(git diff *)"

Long sessions: tmux

If the SSH connection drops, the process in that terminal ends. To keep a session alive across disconnects, run Claude Code inside tmux:

tmux new -s claude
cd /var/www/myapp && claude

Detach without stopping it: Ctrl+B, then D. Reattach:

tmux attach -t claude

List sessions with tmux ls. For several projects, create several tmux sessions with different names.

nohup doesn't suit the interactive mode, which needs a terminal. For background one-off tasks use nohup claude -p "..." > result.txt 2>&1 &.

If a session does drop, you can pick the conversation back up: claude --continue opens the most recent conversation in the current folder, and claude --resume shows a session picker.

Security on the server

• A separate key. Create a key just for this server in your Zukko dashboard↗. Set daily and monthly limits and an allowed model list (for example, only claude-sonnet-5). If the key leaks, the damage is capped by the limit, and you can revoke the key in the dashboard.
• Don't run as root. The agent runs commands with your user's rights.
• Permissions. Don't use --dangerously-skip-permissions on a server with valuable data. Block risky commands with permissions.deny rules in ~/.claude/settings.json or the project settings.
• Don't commit the key. If it ends up in git, delete it in the dashboard and create a new one.

Spend and balance

Check balance and spending history in the dashboard (overview↗, the Usage section) or via the API — see the balance endpoint docs↗. In Zukko, claude-sonnet-5 costs $0.3 per 1M input tokens and $0.3 per 1M output tokens. A session with 1,000,000 input and 50,000 output tokens costs 1 × $0.3 + 0.05 × $0.3 = $0.315. A caveat about caching: vendors charge about 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the normal input price. For an agent with a large, repeated context, the real gap versus official pricing is smaller than a straight price comparison suggests.

If a model is disabled, the gateway returns HTTP 503 with code model_disabled. Pick another model from GET https://api.zukko.pro/v1/models (or the Models page in the dashboard) and update ANTHROPIC_MODEL.

FAQ

Do I need to sign in to an Anthropic account on the server?

No. With ANTHROPIC_AUTH_TOKEN set, Claude Code authenticates with your Zukko key.

How do I get a detailed log?

Start claude --debug-file /tmp/claude.log and watch the file in another tmux window: tail -f /tmp/claude.log.

Can I run several sessions on one server?

Yes, in separate tmux sessions or windows. Each has its own context, and spend goes to whichever key is set in the environment.

How do I update Claude Code on the server?

The official installer's build updates automatically; run claude update to update right away. For apt, dnf and apk, use your normal system package upgrade.