How to Run Claude Code on Zo

Claude Code is Anthropic's terminal-based AI coding agent. It reads your codebase, writes code, runs commands, and manages git. Most guides tell you to set up a VPS, install Node, configure SSH, harden the firewall, and then install Claude Code. On Zo, it's already there.

Why run Claude Code on Zo

Your Zo is a full Linux server in the cloud. Claude Code is pre-installed. That means:

• No VPS setup. No provisioning, no firewall rules, no OS hardening.
• No installation. Claude Code is already at /usr/bin/claude, ready to go.
• Zo's AI works alongside it. Your Zo has its own AI with web search, Gmail, Calendar, file management, image generation, and 100+ other tools. Claude Code handles the coding. Zo handles everything else.
• SSH access from any IDE. Connect VS Code, Cursor, or Windsurf to your Zo and run Claude Code inside the remote terminal.

What you'll need

• A Zo Computer account (any tier)
• A Claude Pro, Max, or Team subscription (for OAuth login), or an Anthropic API key

Step 1: Open Zo's terminal

Click the terminal icon in the left sidebar of your Zo workspace. You're now on your cloud machine.

Step 2: Launch Claude Code

claude

That's it. First launch will prompt you to authenticate.

Step 3: Authenticate

You have two options:

Option A: OAuth login (Claude subscription)

When Claude Code prompts you, select "Sign in with Claude." It opens a browser link. Click it, log in with your Anthropic account, and you're authenticated.

Option B: API key

If you prefer using an API key, go to Settings > Advanced in Zo and add a secret:

ANTHROPIC_API_KEY = your key from console.anthropic.com

Then launch Claude Code. It picks up the key automatically.

Don't paste the key into chat. Use the Secrets panel.

Step 4: Start coding

Navigate to your project directory and run claude. It reads your codebase and you're pair-programming.

cd /home/workspace/my-project
claude

Common things to try:

• "Read this codebase and explain the architecture"
• "Fix the failing test in src/auth.test.ts"
• "Add a REST endpoint for user profiles"
• "Refactor this file to use async/await"

Claude Code writes the code, runs it, checks the output, and iterates until it works.

Step 5: Connect your IDE (optional)

If you prefer coding in your local IDE while Claude Code runs on your Zo, set up SSH:

Your Zo configures SSH and gives you a public address like ts1.zocomputer.io:10991. Add it as a remote host in VS Code, Cursor, or Windsurf.

Now you can edit files in your IDE while Claude Code runs in the remote terminal. Same machine, same filesystem.

For the full IDE setup, see How to Connect Your IDE to a Remote Server.

Using Claude Code and Zo together

This is the part that matters. Claude Code is good at coding. It's not good at sending emails, managing your calendar, searching the web, generating images, or hosting websites. Your Zo does all of that natively.

A typical workflow:

1. Ask Claude Code to build a feature
2. Ask your Zo to deploy it to zo.space
3. Ask your Zo to text you when it's live
4. Ask Claude Code to write tests for it
5. Ask your Zo to set up a daily agent that monitors the deployed service

Two AI systems, one machine, no context-switching. For a deeper look at running multiple coding agents (including Codex CLI and Gemini CLI), see How Zo Runs AI Coding Agents.

Run Claude Code headless

Claude Code supports a headless mode (claude -p) where it runs non-interactively. That means your Zo can launch and control Claude Code sessions on your behalf, with no terminal interaction needed.

The simplest version:

Your Zo starts a Claude Code session, passes the prompt, and reports the results when it's done.

Headless mode with worktrees and PRs

The real power is combining headless Claude Code with git worktrees so it works in an isolated copy of your repo, then opens a PR when it's done. Here's a prompt you can paste directly:

Your Zo handles the git orchestration: creating the worktree, running Claude Code inside it, committing the result, and opening the PR. Claude Code does the coding in a clean, isolated branch. You get a PR link back.

This makes powerful automations possible:

Your Zo orchestrates the session. Claude Code writes the code. The PR appears in GitHub. You review it from your phone — or get a text or Telegram message with the PR link.

Give Claude Code access to Zo's tools

By connecting Claude Code to the Zo MCP server or the Zo/Ask API, Claude Code gains access to everything your Zo can do: web search, email, calendar, file management, image generation, and 100+ other tools.

Set up the connection:

Once connected, Claude Code can do things it normally can't:

• Search the web for documentation while coding
• Send you an email when a long-running task finishes
• Pull context from your Google Drive
• Generate images for a frontend component
• Deploy the project to zo.space when it's ready

Claude Code handles the code. Your Zo handles everything around it. Connected via MCP, they work as one system.

Troubleshooting

• "claude: command not found": This shouldn't happen on Zo. If it does, run which claude to check. If missing, run npm install -g @anthropic-ai/claude-code.
• Authentication fails: Make sure your ANTHROPIC_API_KEY is saved in Settings > Advanced, not pasted in chat. Or use OAuth login instead.
• Session disconnects: If you close the terminal, Claude Code stops. For persistent sessions, use tmux: run tmux, then claude inside it. Detach with Ctrl+B, D. Reattach later with tmux attach.
• Want to use a different model: Run /model inside Claude Code to switch between Claude models.
• Conflicts with Zo's AI: There are none. They're separate processes. Zo's AI operates through the chat interface and scheduled agents. Claude Code operates through the terminal. They share the same filesystem but don't interfere with each other.
• Want other agent frameworks? You can also run OpenClaw or Hermes Agent on the same machine alongside Claude Code.