Docs Start here

Providers, Keys & Models

Blacksite talks to four model providers. You supply the account and the credentials; requests go straight from your machine to that provider’s API. There is no Blacksite server in the path, so your provider’s own dashboard is the authoritative record of what you spent and what you sent.

If model APIs are new to you, start with Choosing a provider and Storing your key. The sections about thinking controls, caching, and provider-specific options are useful later, not requirements for a first request.

Choosing a provider#

Choose it in the Settings panel inside the Blacksite sidebar. The sidebar is the source of truth and mirrors its choice into the user-level blacksite.provider setting, which a new install also reads once as its starting provider.

Why the choice matters less than you’d think#

Blacksite normalizes every provider onto one internal event stream before the agent loop sees it. Five separate streaming implementations converge on a single event type, so switching providers mid-project changes which API is called and nothing else about how the agent behaves. Tool schemas are converted per provider at request time rather than authored several times.

The practical consequence: pick whichever provider you already have billing set up with, and change your mind later without rework.

Following a live request#

The chat activity row shows when Blacksite is waiting for a provider, receiving reasoning or text, preparing a tool call, or retrying a request. The elapsed timer keeps moving during a quiet wait; it measures time in that phase, not token generation. Some models do not expose reasoning text.

Transient failures and incomplete streams are retried within a bounded budget. Partial output from a failed attempt is cleared before the replacement response appears, and the tool log records the reason. Authentication and permission errors stop the request instead of retrying.

Bedrock handles both HTTP throttles and errors inside its event stream. If a model rejects prompt caching, Blacksite retries without cache markers and remembers that choice for the session. These behaviors follow the AWS ConverseStream protocol.

Storing your key#

Using a ChatGPT subscription (experimental)#

In Settings > Model, choose OpenAI, then ChatGPT subscription under Authentication. Click Sign in with ChatGPT and complete the browser sign-in. Blacksite loads the models available through Codex for your account. Select one and send a message as usual; Blacksite still runs its tools through its existing approval checks.

Install a current Codex CLI or the Codex VS Code extension first. Blacksite discovers the extension’s executable or the CLI on PATH. If necessary, set blacksite.chatgpt.codexPath to an absolute executable path and reload the window. For a remote VS Code workspace, Codex must be available on the extension host; browser sign-in also requires access to that host’s local callback port.

The ChatGPT subscription section shows your account and plan, remaining allowance for each reported quota window, reset times, and credits when supplied by OpenAI. It refreshes while the panel is open, after model rounds, and when Codex sends an update. Refresh usage requests a new snapshot. If a refresh fails, the previous snapshot keeps its timestamp and an error is shown; missing limits are never displayed as unlimited. Usage is shared with other Codex clients on your account. These are Codex allowances, not ChatGPT’s chat message limits or an estimate derived from Blacksite token counts.

Codex manages OAuth tokens and refreshes in a separate profile inside Blacksite’s VS Code global storage. Blacksite does not read another Codex installation’s credentials, send tokens to the webview, or store them in workspace settings. Sign out disconnects this profile and stops active subscription model calls.

This integration uses the documented Codex app-server account interface and its experimental dynamic-tool and transcript APIs. A current Codex version is required. Each conversation keeps one Codex thread open. When the model asks for a tool, Blacksite runs it through its own tools and approvals and sends the result back into the same turn, so the model keeps its own reasoning and ChatGPT’s prompt cache, and a step after a tool result starts in a fraction of a second rather than seconds. Blacksite’s transcript stays the source of truth: when it and the thread would disagree (history was compacted or edited, you steered alongside a tool result, the tool list or instructions changed, or the thread was cancelled), Blacksite starts a fresh thread seeded from the transcript instead. Turn blacksite.chatgpt.reuseConversation off to start a new thread for every model call.

Chat, delegated agents using OpenAI, and OpenAI compression use the selected authentication mode. Subscription calls do not fall back to API billing, and Blacksite does not assign API dollar prices to them. API keys remain separately stored; embeddings and audio transcription still require API credentials. Return to API key authentication to use the standard OpenAI API.

What works under ChatGPT sign-in

• Reasoning you can read. ChatGPT sends no reasoning unless it is asked to, so Blacksite asks for summaries and shows them in the thinking stream as the model works. Set blacksite.chatgpt.reasoningSummary to auto, concise or none; the default is detailed. Some models reason without returning a summary even when one is requested, and a model may decide a simple step needs no reasoning at all. When it reasoned but sent nothing, the thinking pane says how many tokens it used instead of staying blank.
• Reasoning depth. The Reasoning Effort control in Settings > Model and the chat’s quick settings list the depths the selected model accepts, from ChatGPT’s own catalog, and show the model’s default until you choose one. The depth is stored separately from the API-key one, so a choice made there (for example Off, which ChatGPT models do not have) never carries over. GPT-5.5 runs at x-high by default and GPT-6-Astra at low. Depths above Max (Ultra, which hands work to ChatGPT’s own sub-agents) are not offered; use Blacksite’s delegation instead.
• Answer length. Every ChatGPT model answers tersely by default (low verbosity). blacksite.chatgpt.verbosity sets low, medium (the default), high, or default to leave the model’s own setting alone.
• Speed. Models that offer a faster tier show a Speed control: Auto leaves the account default, Standard asks for normal speed, and Fast runs the model faster at the higher usage rate ChatGPT lists for it.
• Continuity across tool calls. The model’s own reasoning is passed back with each tool result, so it carries on from where it was rather than starting over. On GPT-6 and GPT-5.6 models this is what stops a model from repeating a tool call it has already made. If ChatGPT refuses the carried reasoning, for example after switching models, the request is retried once without it.
• Context window. Compaction and the usage meter use the window ChatGPT actually gives the model: 258,400 usable tokens by default, not the larger figure the API offers for the same model. Turn on blacksite.chatgpt.extendedContext for the 828,400 that GPT-6 and GPT-5.6 models accept. Long conversations then use more of your allowance.
• Retries and notices. Temporary ChatGPT failures (an overloaded server, a dropped connection) are retried like any other provider’s. Usage-limit and context-window errors are not retried. A model swap by ChatGPT, or a warning from it, appears in the transcript. Models scheduled for retirement show the date in the picker.

What is not connected, on purpose

ChatGPT sign-in gives Blacksite the model, not Codex’s own agent. Codex’s shell, file editing, web search, apps, plugins, memories and multi-agent tools stay off so that every action goes through Blacksite’s tools and approvals. Sampling, output limits and prompt caching follow the model and cannot be changed. Codex’s own conversation storage, review mode and voice features are not used.

Using an API key#

Run Blacksite: Set API Key from the command palette. Choose the provider, paste the key.

Keys go into VS Code’s SecretStorage, which is backed by your OS keychain — Keychain on macOS, DPAPI on Windows, libsecret on Linux. They are never written to settings.json, never written into your workspace, and never written to a log.

You can store a key for more than one provider. Switching provider picks up whichever key matches without re-prompting.

AWS Bedrock#

Bedrock does not use a pasted key. Blacksite resolves credentials through the standard AWS chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. Shared config and credentials files (~/.aws/config, ~/.aws/credentials), including named profiles and SSO
3. Container and instance metadata roles

If aws sts get-caller-identity works in your terminal, Blacksite will authenticate.

Bedrock also has a second choice — the API path, toggled in the sidebar Settings and mirrored to blacksite.bedrockApi:

• converse (default) — the Converse API. Live model listing, dated inference-profile IDs.
• mantle — the Anthropic-native Messages endpoint on Bedrock. Required for the newest Claude models that have not reached Converse yet.

If a model you expect is missing from the list, switching to mantle is the usual fix.

Choosing a model#

Until you pick one, Blacksite uses the provider’s default. Pick a model in the sidebar Settings; the active model is mirrored to blacksite.model for reference, but editing that setting has no effect.

You can also switch mid-conversation with a slash command:

textCopy
/model claude-sonnet-4-6

The model picker in the Settings panel lists what your provider currently advertises, fetched live rather than from a hardcoded table — so a model released this morning shows up today.

What to actually pick#

Agentic coding is unusually demanding on a model. It is not one clever completion; it is dozens of sequential decisions where an early mistake compounds. The heuristics that hold up:

• Frontier models earn their price on hard work. For a multi-file refactor or a subtle bug, a stronger model finishes in fewer turns, and fewer turns is often cheaper overall than a weaker model flailing.
• Cheaper models are fine for mechanical work. Renaming, formatting, writing tests against an already-understood contract.
• Subagents can run on a different model than the main loop. Because the core is provider-neutral, a broad file-triage subagent can use something cheap while the orchestrating loop stays on something strong. You do not have to pick one model for everything.

Thinking and reasoning effort#

Claude models expose a thinking budget, and the shape of that control changed across model generations. Blacksite handles the difference for you, but it helps to know what is happening:

• Adaptive thinking (Opus 4.6+, Sonnet 4.6+, Fable 5): the model decides when and how deeply to think. Depth is steered by an effort level rather than a token count. The ladder runs low → medium → high → xhigh → max, and high is the default.
• Budgeted thinking (Claude 3.7 through 4.5): a fixed budget_tokens allowance.
• No thinking: everything else.

Which dialect a request uses is a function of the model, not a global setting, and the newer models reject the older shape outright. Blacksite picks the right one per model — including for models released after this build, which it assumes speak the newest dialect rather than failing closed.

Raise effort for genuinely hard reasoning: root-causing a race condition, planning a migration. Leave it at the default for ordinary work. Thinking tokens are billed like any other output tokens.

What a request actually costs#

An agent loop resends the whole conversation on every iteration. That sounds ruinous, and it would be without prompt caching.

Providers will cache a prefix of your request and charge far less to re-read it. The rule that makes it work is that caches key on an exact prefix — anything that changes invalidates everything after it. So Blacksite orders each request stable-content-first (system prompt, tool schemas, early conversation) and volatile-content-last, and places a cache breakpoint just before the volatile tail on every provider path that supports it.

The visible consequences for you:

• Long conversations are much cheaper than their token count suggests. Most of the prefix is a cache hit.
• Starting a fresh conversation is not free. The first turn re-pays for the whole prefix. Continuing an existing thread is usually the cheaper move.
• Compaction costs one model call. It buys back context room; see Working with Chat.

The Inspector (the ⓘ button in the chat header) shows live token accounting for the current conversation — what is in context, what was cached, and what the last turn consumed.

MCP servers#

Beyond the built-in tool surface, Blacksite can connect to Model Context Protocol servers, which expose additional tools to the agent.

Run Blacksite: Manage MCP Servers to add one, or Blacksite: Import MCP Servers… to add servers you already set up in VS Code, Claude Code, Claude Desktop, Cursor or Windsurf. Both transports are supported:

• stdio — a local command Blacksite launches and talks to over pipes. The process is started once and kept warm, so an npx-launched server pays its boot cost on the first call, not every call.
• http — a remote server. Blacksite speaks Streamable HTTP (MCP 2025-03-26 and later) and falls back to the legacy HTTP+SSE transport (2024-11-05) automatically, so you do not need to know which revision your server implements. Override the probe under Protocol if a server mis-advertises itself.

Authentication#

Four modes, chosen per server:

OAuth needs no setup: press Sign in and Blacksite discovers the server’s authorization server, registers itself dynamically, and runs the standard authorization-code flow with PKCE in your browser. Tokens are refreshed silently and re-authorization is prompted only when a refresh is refused. If your server does not support dynamic registration, paste a client ID and its redirect URI instead.

For stdio servers, credentials usually arrive as environment variables — add them under Environment and leave the value blank to have it prompted for and stored as a secret.

Every credential — OAuth tokens, static tokens, secret environment values — is kept in VS Code SecretStorage. None of it is written to settings.json, to workspace state, or to any log, and none of it is ever visible to the model.

Choosing which tools the agent gets#

Press Discover tools on a server to list everything it offers, then switch individual tools on or off. This is the point of the panel: a server with ten useful tools and one you would rather it never touched is a normal situation.

A tool switched off is not merely blocked at call time — it is removed from the catalog the agent receives, and a call to it answers exactly as the server answers a name it has never had. The agent is never told the tool exists, so it cannot reason about it, work around it, or lobby you to enable it.

The New tools setting decides what happens to a tool that appears after you last looked. Leaving it allowed means a server upgrade does not silently break a working setup; setting it to withheld holds the server to exactly the tools you have reviewed. Disable all sets it to withheld for you.

Each entry can be enabled or disabled without being deleted, and the agent sees only the tools from enabled servers. Blacksite lists a newly added or edited server’s tools in the background, and re-lists a server that announces its tools changed, so Discover tools is only needed to check a server right away.

Every project, or this one#

A server is available either in all projects or in this project only. New servers default to all projects: they are saved in your user settings (blacksite.mcpServers) and appear in every folder you open, with the same credentials and tool choices. A project-only server is kept with the workspace. Share with all projects and Make project-only move a server between the two. Removing an all-projects server asks whether to remove it everywhere or only hide it in this project.

In blacksite.mcpServers you can write a server the way most MCP READMEs do — command, args, and an env object — and ${env:NAME}, ${workspaceFolder} and ${userHome} are expanded. See Settings & Commands.

Prompts, resources and the log#

Blacksite: Use MCP Prompt… lists the prompts your servers offer, asks for their arguments, and attaches the result to your next message. Blacksite: Attach MCP Resource… does the same for a document or record a server publishes. The agent can also list and read resources itself.

Blacksite: Show MCP Log (or Log in the panel) shows each server’s start-up, the transport and protocol it settled on, its own error output, and every call with its timing. Credentials never appear in it.

MCP tools are subject to the same approval gates as built-in ones, with Always allow per tool — see MCP servers are third parties. A remote MCP server is a third party in your loop — extend it the same trust you would extend to any dependency you install.

Related#

• Getting Started — installation and first request
• Settings & Commands — the full settings reference
• Approvals & Safety — what leaves your machine, and when