Skip to content
NBS Workshop

Setup · Claude Code (terminal)

For Day 1 afternoon · runs on macOS, Linux, Windows (WSL)

Prerequisites

  • Node.js 20 or later — verify with node --version
  • GCP project with the Vertex AI API enabled
  • Anthropic model access in Vertex AI Model Garden (allow 1 – 2 business days for approval)
  • gcloud CLI installed and authenticated — verify with gcloud auth list

Install

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

Authenticate

Use Application Default Credentials (the easiest path for the workshop):

Terminal window
gcloud auth application-default login

Configure for Vertex

Add to your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

Terminal window
export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=<your-gcp-project-id>
export CLOUD_ML_REGION=asia-northeast1
export ANTHROPIC_MODEL=claude-sonnet-4-6@20250514

Reload the shell or open a new terminal.

Verify

A one-line round-trip to confirm the install + auth + routing:

Terminal window
claude --print "Reply with the single word: ready"

Expected output: ready. If you see that, the install is good.

Build the hello-world agent

Terminal window
mkdir agent-workshop && cd agent-workshop
mkdir -p .claude/agents


cat > .claude/agents/file-reader.md <<'EOF'
---
agent_id: file-reader
model: claude-sonnet-4-6
---


# Identity
I am a file-reader. I read files in the working directory and summarise them.


# Workflow
When invoked:
1. List files in the current directory
2. Read the most recent .md or .txt file
3. Print a 3-line summary
4. Exit
EOF


echo "# Hello World" > sample.md
echo "This is my first file." >> sample.md


claude --agent file-reader

Expected: the agent lists files, reads sample.md, and prints a 3-line summary.

Troubleshooting

claude: command not found — the npm global bin is not on PATH. Run npm config get prefix and add <that-path>/bin to PATH.

401 Unauthorized from Vertex — re-run gcloud auth application-default login. Confirm ANTHROPIC_VERTEX_PROJECT_ID matches your active GCP project (gcloud config get-value project).

Model not available in region — confirm Anthropic Claude model access is granted in Vertex AI Model Garden for the asia-northeast1 region. Approval can take 1 – 2 business days.

Corporate proxy blocking the API — confirm asia-northeast1-aiplatform.googleapis.com is allowed for outbound HTTPS.