Use Claude Code From Your Phone With an API Key or Proxy

The short answer

If you run Claude Code with an API key, an LLM gateway, a third-party proxy or Amazon Bedrock, the official Remote Control feature won't work for you. It requires a claude.ai subscription login and only works when requests go straight to api.anthropic.com. To check tasks, approve tool calls and keep chatting from your phone, your realistic options are SSH + tmux, a hooks-based notification tool, or an app that runs next to Claude Code on your computer, such as BotBus. If you pick BotBus, there is one trap worth knowing up front: turns started from the phone are launched by BotBus, so they don't see the export lines in your ~/.zshrc. Your gateway URL and key need to live in the env block of ~/.claude/settings.json.

We checked the Claude Code details below against the official Remote Control, environment variables and settings docs on October 4, 2026. Claude Code changes quickly, so treat the official docs as the source of truth. For a general comparison of Remote Control and its alternatives, see Claude Code Remote Control alternatives; this post focuses on the API key and proxy case.

Why Remote Control is off the table

The Requirements section of the Remote Control docs is explicit:

It is available on Pro, Max, Team and Enterprise plans. API keys are not supported.
It does not work if you use Amazon Bedrock, Google Cloud or Microsoft Foundry, if you point ANTHROPIC_BASE_URL at any host other than api.anthropic.com (an LLM gateway or proxy, for example), or if you sign in through an enterprise Claude apps gateway.

The environment variables reference adds that as of v2.1.196, Remote Control is disabled whenever ANTHROPIC_BASE_URL points somewhere else. Even with a claude.ai login, an active ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or apiKeyHelper triggers a "requires claude.ai subscription auth" error.

So this isn't a misconfiguration on your side. The official feature simply doesn't cover these setups, which is why people on gateways, regional model providers or company proxies go looking for something else.

Options that do work

SSH + tmux. Run claude inside tmux and attach from an SSH client on your phone. Because it's your login shell, your proxy variables apply as usual, and any auth method works. The cost: you have to make your computer reachable (VPN or a tunnel), typing in a terminal on a phone is tiring, and there are no notifications. If the agent stops to wait for you, you won't know until you look.

Hooks-based notifiers. Several community tools use Claude Code hooks to forward permission requests and completion events to ntfy, Telegram and similar services. Hooks run inside the claude process you started, so your auth method doesn't matter. They're a good fit if all you want is "don't let approvals stall". Check which server your messages pass through, and whether a timeout means allow or deny.

BotBus. A menu bar app for the Mac that syncs tasks from Claude Code, Codex and other local agents to iPhone and Apple Watch, with end-to-end encrypted content. It doesn't care how your Claude Code is authenticated; it runs the claude you already installed. The rest of this post covers how to set it up with a proxy.

Two kinds of sessions, two environments

BotBus sees Claude Code work from two places, and they get their environment variables from different sources.

Sessions you start in a terminal. Once you install the hooks from BotBus settings, you keep running claude in your terminal as usual, and session status and permission requests reach your phone through the hooks. Your shell started that process, so ANTHROPIC_BASE_URL and your key from .zshrc are present. Nothing to change.

Turns you start or continue from the phone. BotBus launches claude -p on your Mac, and approvals for that turn travel over its stdin and stdout to your phone. That child process inherits BotBus's own environment. A Mac app opened from the Dock, Launchpad or Login Items never runs your ~/.zshrc. The symptom: everything works in the terminal, but a task started from the phone talks to the default endpoint without your key and fails with "not logged in" or "invalid API key", which the phone shows as a sign-in problem.

Claude Code has a shell-independent fix. Per the environment variables reference, variables placed in the env key of settings.json are read directly from the file, so they take effect no matter how claude was launched.

Setup

1. Confirm it works in a terminal

Run claude -p "reply ok" once. If your gateway, key or model name is wrong here, the phone won't fix it.

2. Move your exports into the env block

Open ~/.claude/settings.json (create it if needed; if you installed the BotBus hooks there is already a hooks section, so keep it) and add or merge an env object. A gateway example:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "your-token",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "model-id-on-your-gateway",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "model-id-on-your-gateway",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "model-id-on-your-gateway"
  }
}

Pick the auth variable your gateway expects. ANTHROPIC_AUTH_TOKEN is sent as an Authorization: Bearer header. ANTHROPIC_API_KEY is sent as X-Api-Key, and the docs note that in -p mode it is always used when present, overriding a subscription login. For Bedrock, set CLAUDE_CODE_USE_BEDROCK to 1 plus AWS_REGION, and AWS_PROFILE if that's how you pick credentials.

3. Scope it to one project if you prefer

env in ~/.claude/settings.json applies to every Claude Code session, terminal ones included. To route only one project through the gateway, put the block in that project's .claude/settings.local.json, the personal per-project layer. BotBus runs phone-started turns inside the project directory, so they pick it up too. Don't put keys in the project's .claude/settings.json; that file usually gets committed.

4. Keep the key out of plain text

settings.json is plain text. The official apiKeyHelper setting runs a command of your choice to produce the credential, for example one that reads it from the macOS Keychain, so the file holds only a path.

5. Simulate a launch without your shell config

Before reaching for your phone, run Claude Code with an almost empty environment:

env -i HOME="$HOME" "$(command -v claude)" -p "reply ok"

Only HOME survives, so nothing from .zshrc is present. That's close to what BotBus sees. If it replies, your config no longer depends on the shell; create a task from your phone to confirm.

Models and images from the phone

When you start or continue a Claude Code task on the phone you can pick a model and a reasoning effort. Claude Code has no model-listing API, so the phone shows the aliases --model accepts (Fable, Opus, Sonnet, Haiku) and passes the alias to claude. Behind a gateway, what an alias resolves to is controlled by the ANTHROPIC_DEFAULT_*_MODEL values in your env. If you don't pick one, no --model is passed and your configured default applies. Effort levels come from your local claude --help; whether your backend honors them depends on that backend.

You can attach images to a Claude Code turn from the phone. BotBus puts them in the message it hands to claude, so if your model can't read images, the turn will fail. BotBus can't work around that.

Limits

Your gateway still sees what goes to the model. BotBus's end-to-end encryption covers the hop between your phone and computer through the BotBus server: tasks, conversations and approvals are encrypted on device, and the server sees only routing metadata such as device IDs, online status, update times and payload sizes. Dev previews are outside end-to-end encryption. Details are in the security notes. What claude sends to your proxy or model provider is governed by that provider, not BotBus.
Your computer must be on and online. claude runs there; the phone is a remote. Approving, continuing, starting and stopping tasks all need that computer and BotBus online, and depend on the task's current state.
Stopping only works on processes BotBus started. Stop terminal sessions from the terminal.
Platforms. On the computer side there's a Mac app (a menu bar app, macOS 26 or later) and a Linux version (a command-line program for x86_64 and aarch64; see the install guide); the environment notes in this post are about the Mac app. The iPhone and Apple Watch app is available on the App Store. Windows and Android versions are planned.
BotBus doesn't manage your auth. It neither reads nor edits your gateway settings and can't tell whether a proxy is trustworthy. If claude works on your computer, it works from your phone.

To try it, download it for your computer. If approvals are your main concern, read how to approve Claude Code permission requests from your phone.

FAQ

My gateway URL is exported in .zshrc and the terminal works. Why do phone-started tasks say I'm not logged in?

Phone-started turns run claude -p under the BotBus app's environment, which never sources .zshrc. Put the variables in the env block of ~/.claude/settings.json; Claude Code reads them from the file.

Will my terminal sessions use the gateway too after that?

Yes, the user-level env applies to every session. To limit it to one project, use that project's .claude/settings.local.json.

I'm logged in to claude.ai and also have an API key in env. Which one is used?

According to the docs, ANTHROPIC_API_KEY is always used in -p mode when present, and interactive mode asks you once before it overrides your subscription. Phone-started turns use -p, so they bill to the key.

Can I still approve permission requests from a terminal session that uses a proxy?

Yes. Terminal sessions forward permission requests to the phone through the hooks BotBus installs, regardless of how Claude Code reaches the model.

Does BotBus get my API key?

BotBus doesn't use your key. It launches your claude, which reads the key from its own config, and the key never passes through the BotBus server. Installing hooks only rewrites the BotBus entries under hooks in settings.json; env and your other settings are kept as they are.