The claude-code runner invokes the claude CLI binary as a subprocess. It is the default runner because it works with a Claude Pro or Max subscription — no Anthropic API key required. If you already pay for Claude, you can use claude-code at no additional cost.
Requirements
-
The
claude CLI installed globally:
npm install -g @anthropic-ai/claude-code
-
Authentication — see Authentication below.
Verify the binary is available:
Authentication
The claude binary must be authenticated before the agent can use it. There are four options:
Option A — Long-lived OAuth token (recommended for servers)
Generate a token once with:
This creates a token (of the form sk-ant-oat01-...) that is valid for one year and works on any machine without re-login. It is the best option for running the agent on a remote server or a machine you cannot easily log in to interactively.
claude setup-token requires an active Claude Pro or Max subscription.
The token is shown only once — copy it immediately before closing the terminal.
remoteagent init, the wizard will ask for this token and store it in the agent config. The token is injected automatically each time the claude binary is invoked — no shell export needed.
Option B — Interactive login
Authenticate interactively on the machine where the agent runs:
This stores a session credential managed by the claude CLI itself. Sessions expire periodically and must be renewed manually by running claude login again on the same machine. Best for local development machines you have direct access to.
Option C — Third-party provider (Amazon Bedrock, Google Vertex AI, Microsoft Azure)
If your organisation accesses Claude through a cloud provider rather than a direct Anthropic subscription, run:
The wizard lets you choose your provider and enter the required credentials (AWS IAM keys for Bedrock, a GCP service account JSON for Vertex AI, or an Azure endpoint for Foundry). Credentials are saved locally by the claude binary — they are never transmitted to RemoteAgent.
During remoteagent init, choose “Third-party provider” in the authentication step and the wizard will run claude /login for you.
Option D — API key
If you have an ANTHROPIC_API_KEY set in your environment, the claude binary will use it automatically.
ANTHROPIC_API_KEY takes precedence over your subscription — it overrides
both the OAuth token and claude login, even with an active Pro/Max plan.
Unset it if you want to authenticate via subscription:Setup
remoteagent init --runner claude-code
claude-code is the default.
Token expiry
The dashboard shows a warning when your OAuth token is close to expiring. To renew it, run claude setup-token again on the same machine and re-run remoteagent init to update the stored token.
Difference from claude-sdk
| claude-code | claude-sdk |
|---|
| Auth | OAuth token or claude login (subscription) | Anthropic API key |
| API cost | Included in Pro/Max subscription | Billed per token |
| Execution | Subprocess (claude binary) | In-process (Node.js SDK) |
| Startup overhead | ~200–500ms per invocation | None |
claude-sdk if you prefer direct API access and per-token billing over a subscription.
Updating the binary
npm update -g @anthropic-ai/claude-code
claude --version
