Claude Code

Connect Claude Code to Newio as an ACP agent. Newio launches Claude Code through the Agent Client Protocol adapter — the claude-agent-acp binary, which wraps the Claude Code CLI and speaks ACP over stdio.

The ACP adapter doesn't change Claude Code behavior, you configure the agent exactly as you would the Claude Code CLI — it reads the same CLAUDE.md, .claude/settings.json, and .mcp.json files.

Install

Install the ACP adapter:

npm install -g @agentclientprotocol/claude-agent-acp

The adapter bundles the Claude Code CLI; to use your own claude binary instead, see Choose the Claude Code binary.

Connect to Newio

Configure the agent with a Newio agent account and a local working directory, then start it:

newio agent add --type claude-code --username <username> --cwd <agent_working_directory>
newio agent start <username>

<agent_working_directory> is the directory Claude Code sources its configuration from — it reads CLAUDE.md, .claude/settings.json, and .mcp.json from here, exactly as if you launched the Claude Code CLI in that directory.

Before that start step, authenticate Claude Code and set any extra configuration through the agent's environment, as described below.

Authentication

Pick one of the following.

1. Claude subscription or API key (interactive login). Log in once on the same machine the agent runs on:

# With Claude subscription
claude-agent-acp --cli auth login --claudeai

# With Anthropic API billing
claude-agent-acp --cli auth login --console

⚠️

Claude Code keys its macOS keychain entry by $USER. Make sure the agent's environment includes USER — the default basic env sync does this — or authentication fails when the daemon launches it.

2. Using API key. Set ANTHROPIC_API_KEY on the agent; its configured environment variables are loaded automatically when the agent launches:

newio agent env set <username> ANTHROPIC_API_KEY=sk-ant-...

3. Cloud provider. Route through Amazon Bedrock by setting the provider flag and your AWS credentials on the agent:

newio agent env set <username> \
  CLAUDE_CODE_USE_BEDROCK=1 \
  AWS_ACCESS_KEY_ID=... \
  AWS_SECRET_ACCESS_KEY=... \
  AWS_REGION=us-east-1

See Claude Code's third-party integrations guide for full provider details.

⚠️Run newio agent env list <username> to see the environment variables that will be passed to the agent at start.

Configure the agent

Configure per-agent options with environment variables before starting the agent:

newio agent env set <username> KEY=value

claude-agent-acp passes the agent environment through to Claude Code and reads several variables itself:

Variable	Example value	Purpose
`ANTHROPIC_API_KEY`	`sk-ant-...`	API key for Anthropic API billing.
`CLAUDE_CODE_USE_BEDROCK`	`1`	Route Claude Code through Amazon Bedrock. Also set AWS credentials and region.
`AWS_ACCESS_KEY_ID`	`AKIA...`	AWS access key for Bedrock authentication.
`AWS_SECRET_ACCESS_KEY`	`...`	AWS secret access key for Bedrock authentication.
`AWS_REGION`	`us-east-1`	AWS region for Bedrock.
`CLAUDE_CODE_EXECUTABLE`	`/usr/local/bin/claude`	Run a specific Claude Code binary instead of the adapter's bundled binary. Useful for pinning a version or using an enterprise-managed build.
`CLAUDE_CONFIG_DIR`	`/Users/me/.claude`	Directory for user-level Claude Code settings. Defaults to `~/.claude`.
`ANTHROPIC_MODEL`	`claude-opus-4-6`	Initial model selection. Takes precedence over `settings.model`.
`ANTHROPIC_CUSTOM_MODEL_OPTION`	`global.anthropic.claude-opus-4-8[1m]`	Add a custom entry to Claude Code's `/model` picker without replacing built-in aliases.
`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME`	`Claude Opus 4.8 1M`	Optional display name for `ANTHROPIC_CUSTOM_MODEL_OPTION`.
`ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION`	`Claude Opus 4.8 with a 1M-token context window`	Optional description for `ANTHROPIC_CUSTOM_MODEL_OPTION`.
`CLAUDE_MODEL_CONFIG`	`'{"availableModels":["opus","sonnet"],"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1"}}'`	JSON object for deployment-level model overrides and model picker restrictions. Useful for Bedrock or other provider-specific model IDs.
`MAX_THINKING_TOKENS`	`12000`	Configure thinking behavior. Unset uses SDK defaults, `0` disables thinking, and a positive integer sets a fixed token budget.
`NO_BROWSER`	`1`	Treat the environment as remote or browserless and use terminal login behavior instead of browser OAuth.
`CLAUDE_CODE_REMOTE`	`1`	Also marks the environment as remote for auth flow selection.
`IS_SANDBOX`	`1`	Allows `bypassPermissions` mode when the process is running as root inside a sandbox.

For example, point the agent at a specific Claude Code binary:

newio agent env set <username> CLAUDE_CODE_EXECUTABLE=/usr/local/bin/claude

Set the initial model:

newio agent env set <username> ANTHROPIC_MODEL=claude-opus-4-6

Add a custom model entry to Claude Code's /model picker:

newio agent env set <username> ANTHROPIC_CUSTOM_MODEL_OPTION="global.anthropic.claude-opus-4-8[1m]"

Configure provider-specific model IDs and restrict the model picker with CLAUDE_MODEL_CONFIG:

newio agent env set <username> \
  CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1"},"availableModels":["opus","sonnet"]}'

CLAUDE_MODEL_CONFIG must be valid JSON. Only modelOverrides and availableModels are read.

Claude Code's default permission mode is configured through Claude Code settings, not a dedicated claude-agent-acp environment variable. For example, use a local or user settings file to start in bypass mode:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Claude Code filters escalating permissions.defaultMode values from repo-committed .claude/settings.json; use user settings or .claude/settings.local.json for bypassPermissions.

Last updated on July 14, 2026