Connectors
A connector is a ready-made provider login for the whole workspace. You log in to the provider once (or paste a token), the workspace keeps the credential, and every sandbox you create with the connector attached talks to the provider through the credentials proxy. The agent inside the sandbox gets a working client and a placeholder token, never the real credential.
Connectors and integrations
An integration is the general mechanism: a target URL, a workspace env that holds the credential, and how the proxy injects it. You define integrations yourself, see integrations and the credentials proxy.
A connector sits on top of integrations. It knows the provider, stores your credential in the right workspace env, creates and manages its integrations for you, and also configures the provider's tools inside the sandbox (base URLs, placeholder tokens, config files). With a plain integration, pointing the client at the proxy is up to you.
Available connectors
| Connector | Provider | Credential (workspace variable) | Integrations |
|---|---|---|---|
claude | Claude Code | OAuth token from a Claude subscription (CLAUDE_CODE_OAUTH_TOKEN), or an Anthropic API key (ANTHROPIC_API_KEY) | claude |
github | GitHub | OAuth token or personal access token (GH_TOKEN) | github, github-api |
codex | OpenAI Codex | ChatGPT login (CODEX_AUTH_JSON), or an OpenAI API key (OPENAI_API_KEY) | chatgpt (ChatGPT login) or openai (API key) |
The credential is stored as a sensitive environment variable of the workspace service, so you also see it among the service's environment variables in the Zerops GUI. zbox connector list shows the kind of the stored credential, its variable and the integrations it uses.
Connectors are being reworked into a generic mechanism, with many more providers to connect.
Connect a provider
The easiest way is the provider's own browser login. zbox connector login starts a helper sandbox, runs the provider's login command in it (claude setup-token, gh auth login --web, or codex login --device-auth) and attaches your terminal. Open the link it prints and finish the login in your browser; Claude Code then asks you to paste the code the browser shows, Codex gives you a one-time code to enter in the browser. The workspace picks up the credential, stores it and terminates the helper sandbox, which closes your terminal.
The login needs an interactive terminal. If you close the terminal, the helper sandbox is terminated shortly after; a login you leave open without finishing is abandoned after 15 minutes. In the console, the same flow is the Connect in browser button in the Connectors section of the Integrations page.
The helper sandbox boots from the most recently added ready base, not from the default base, and that base must contain the provider's CLI. The default base has claude, gh and codex. If you added another base after it, the terminal shows command not found (or the login fails right away when the base can't run a shell); exit the shell and store a token instead.
If you already have a token or an API key, store it directly. The value is read without echo from the terminal, or from stdin when piped, never from the command line. The kind (OAuth token or API key) is detected from the value; --kind overrides it.
In the console, use Paste a token. Storing a credential replaces the previous one, including one of the other kind.
Use a connector in a sandbox
A connector does not apply to sandboxes automatically. Attach its integrations when you create the sandbox:
In the console's new sandbox form, tick the connector under Log in as; that attaches all of its integrations.
Attach them at create. The tools are configured when the sandbox boots, so an integration attached later with zbox attach is routed through the proxy right away, but the tools inside the sandbox are pointed at it only after the next cold boot (park with --no-memory and wake).
What the tools in the sandbox get:
| Connector | Tools | Set up in the sandbox |
|---|---|---|
claude | claude | ANTHROPIC_BASE_URL points at the proxy, a placeholder token, onboarding marked as done, sessions start in auto permission mode |
github | git, GitHub REST API clients | https://github.com/, git@github.com: and ssh://git@github.com/ remotes are rewritten to the proxy, so clone and push work without a key; GITHUB_API_URL points at the proxy; /etc/gitconfig gets the name and email of the token's GitHub account |
codex | codex, OpenAI SDKs (API key) | /etc/codex/config.toml points Codex at the proxy, ~/.codex/config.toml defaults to no approvals and full access; with an API key also OPENAI_BASE_URL and a placeholder OPENAI_API_KEY |
Settings you put in the image or the sandbox win: the Claude Code files only get the top-level keys they lack, the Codex user config and the git identity are only written when missing, and a git setting at the global or repository level overrides the system one.
gh is not authenticated through the GitHub connector, because it cannot talk to the proxy. Use git and the REST API, or deliver the token to the sandbox as a secret (--secret GH_TOKEN), which puts the real credential inside the sandbox.
The proxy reads the credential on every request, so storing a new one of the same kind applies to running sandboxes right away. Switching the kind (for example from a Claude subscription token to an API key) changes the placeholder and the tool configuration too, which running sandboxes get only at their next cold boot.
Drop a credential
This removes the credential from the workspace. The connector's integrations stay, and sandboxes that use them get the proxy's 502 credentialMissing error until you store a credential again. In the console, use Disconnect.
Storing the first credential creates the connector's integrations. To get rid of them too, drop the credential and remove them once no sandbox has them attached: