# Core documentation — complete corpus

Canonical index: https://docs.core.so/README.md
Production documentation only. Public facts do not grant account authority.

---

Canonical source: https://docs.core.so/api-keys-and-inference.md

# Model router and project keys

Use this document when an application needs to call models. Account-level agent access uses `core_mk_`; application code uses a project-scoped `core_sk_`.

## Create a project key

Run the key flow locally. The key is injected without being printed.

```sh
npx @core-so/login key create --project weather-app
npx @core-so/login key run --project weather-app -- npm test
```

`key run` exposes `CORE_API_KEY` only to the child process. Never put a Core key in source code, browser JavaScript, logs, or an AI transcript.

## Call a model

```sh
curl -s https://router.core.so/v1/model/messages \
  -H "Authorization: Bearer $CORE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"Hello"}]
  }'
```

## Request rules

| Field or header | Rule |
|---|---|
| `model` | Use a model id returned by Core. |
| `max_tokens` | Required. Requests above the per-call spend ceiling are rejected before dispatch. |
| `stream` | Optional boolean. Usage and cost are returned in-band when streaming. |
| `x-core-cost-micro` | Observed cost in micro-dollars. |

Count tokens before a large request:

```sh
curl -s https://router.core.so/v1/model/count_tokens \
  -H "Authorization: Bearer $CORE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Hello"}]}'
```

## Related

- [Account access](https://docs.core.so/mcp-account-access.md)
- [Billing and credits](https://docs.core.so/billing-and-credits.md)
- [Build](https://build.core.so)

---

Canonical source: https://docs.core.so/billing-and-credits.md

# Billing and credits

Use this document when reasoning about who pays, how spend is limited, or whether a failed operation is charged.

## Account model

| Object | Billing behavior |
|---|---|
| Organization | Owns one shared credit balance. |
| Agent | Spends from its organization and receives attribution. |
| Project key | Spends from one grant and receives independent attribution and revocation. |
| User | Acts through organizations; there is no separate per-user wallet. |

Every user receives a personal organization at signup. Team organizations use the same model.

## Charge lifecycle

1. Core verifies the exact capability definition.
2. The spend kernel authorizes a maximum amount.
3. The operation runs.
4. Success captures observed cost, capped by the authorization.
5. Failure voids the authorization and charges `$0.00`.

Spend limits are deterministic. An AI model cannot waive them. An unavailable billing service returns a service error; it must not be interpreted as insufficient credits.

## Manage spend

Use [Build account settings](https://build.core.so/account) to view balance, add credits, inspect receipts, and manage limits. Use separate project keys when attribution or revocation must be isolated.

## Related

- [Model router and project keys](https://docs.core.so/api-keys-and-inference.md)
- [Account access](https://docs.core.so/mcp-account-access.md)

---

Canonical source: https://docs.core.so/building-apps.md

# Building apps with Core Agent

Use this document when the desired outcome is a working application rather than a single API call.

## Build

Give the agent the outcome, constraints, and acceptance checks. The agent works in its durable workspace, runs the project, and returns a live preview.

```text
Build a mobile-first support dashboard. Use the existing repository,
run its tests, and give me a live preview before publishing.
```

## Add Core services

When the project needs inference or capabilities, approve **Use Core** in the environment request. Core creates a project-scoped `core_sk_` and stores it outside the repository and conversation.

Server-side application routes:

| Route | Purpose |
|---|---|
| `POST /api/ai/chat` | Model messages. |
| `POST /api/ai/<capability>` | Search, images, speech, research, or another routed capability. |
| `GET /api/ai/status` | Check whether Core is configured. |

Do not call paid Core services from browser code and do not commit credentials.

## Preview and publish

1. Ask the agent to start the application.
2. Validate the live preview.
3. Give corrections in the same task.
4. Ask the agent to publish after acceptance checks pass.

The preview and published service receive secrets as server-side configuration; keys are not copied into build artifacts.

## Related

- [Core Agent](https://docs.core.so/core-agent.md)
- [Model router and project keys](https://docs.core.so/api-keys-and-inference.md)

---

Canonical source: https://docs.core.so/core-agent.md

# Core Agent

Core Agent is a durable autonomous employee with its own workspace and execution environment. Closing a browser does not cancel its work. Open it at [core.so](https://core.so).

## Core objects

| Object | Meaning |
|---|---|
| Agent | Persistent identity, memberships, workspace, integrations, and policy. |
| Task | Shared conversation and work history owned by one agent. |
| Run | One durable execution for a task. |
| Workspace | Files, repositories, previews, and published artifacts the agent operates. |
| Automation | Scheduled or event-triggered work. |

One run is active per task. Follow-ups queue; guidance sent during a run can steer the active work. Team members with access to the agent see the same tasks, runs, and workspace.

## Give work

Specify the outcome and acceptance conditions, then let the agent choose implementation steps.

```text
Audit our checkout flow, fix the highest-impact failure,
verify it in the browser, and report what changed.
```

Use a task for complex work that benefits from the user's existing workspace, integrations, memory, or judgment. Use direct account reads for known structured state.

## Capabilities

- Build and operate software in a durable environment.
- Browse, research, and produce files or published artifacts.
- Use connected services through scoped plugins.
- Continue work across devices and team members.
- Run scheduled or event-triggered automations.

## Related

- [Building apps](https://docs.core.so/building-apps.md)
- [Account access](https://docs.core.so/mcp-account-access.md)

---

Canonical source: https://docs.core.so/core-store.md

# Tool store and rankings

Use this document to discover a model, tool, plugin, or app. Build owns developer controls; Rankings owns public comparison data.

## Surfaces

| Surface | URL | Purpose |
|---|---|---|
| Build | https://build.core.so | Account access, project keys, testing, and publishing. |
| Rankings | https://rankings.core.so | Intelligence, cost, popularity, and comparisons. |
| Popularity | https://rankings.core.so/leaderboard | Observed usage rankings. |
| Compare | https://rankings.core.so/compare | Side-by-side models and tools. |

## Search supply

Catalog search is public and read-only.

```sh
curl -s https://build.core.so/api/search \
  -H "content-type: application/json" \
  -d '{"query":"scrape a web page","limit":5}'
```

| Supply | Meaning |
|---|---|
| Model | Routed inference with published price and evidence. |
| Tool | Callable capability with a pinned schema. |
| Plugin | User-owned service connection; credentials do not enter the catalog. |
| App | Content-pinned installable artifact. |

## Trust and pins

A definition pin hashes the callable schema Core vetted. Core re-verifies it before paid dispatch. Schema drift causes trust `0`, suspension, and dispatch refusal. An unreachable endpoint lowers trust and ranking but is not classified as schema drift. Reviews may affect ranking; they cannot bypass a pin or restore a drifted definition.

Missing measurements remain missing. Do not interpret “not measured” as zero, and do not infer callability from a ranking page.

## Related

- [Publishing tools](https://docs.core.so/publishing-supply.md)
- [Account access](https://docs.core.so/mcp-account-access.md)

---

Canonical source: https://docs.core.so/mcp-account-access.md

# MCP account access

Use this document when Codex, Claude Code, or another trusted AI agent must act through a user's Core account.

## Connect

Codex setup is one command:

```sh
npx -y @core-so/login@0.1.5 connect codex
```

It opens browser approval, stores the account connection outside the transcript,
and configures Core's first-party MCP adapter. Start a new Codex task after it
finishes.

Clients with working remote MCP OAuth can connect directly to:

```
https://core.so/mcp
```

For other clients, `npx -y @core-so/login --store https://build.core.so --client
<client-name>` is the fallback. It never prints the saved `core_mk_` credential.
Never paste one into a prompt.

## Choose a primitive

| Tool | Use when | Effect |
|---|---|---|
| `core_docs_search` | A stable public Core fact is needed. | Read-only. |
| `core_account` | Known structured account state is needed. | Read-only. |
| `core_ask` | A message or task needs the user's agent, context, workspace, or integrations. | Starts a durable task. |
| `core_tool_search` | A callable capability must be discovered. | Read-only. |
| `core_tool_invoke` | One exact search result should run. | Starts an asynchronous operation. |
| `core_operation_get` | An operation must be polled or resumed. | Read-only operation state. |
| `core_operation_cancel` | An operation must stop. | Cancels the named operation. |

Routing order: read structured state directly; search public docs for stable facts; delegate complex work with `core_ask`; search before invoking a tool.

## Operations

`core_ask` and `core_tool_invoke` return an `operation_id` and `task_url`. If the
user asked only to send or delegate, return the task link without polling. If
they asked for the result, poll the same id with `core_operation_get`. Supply a
stable `idempotency_key` when submission may be retried.

If state is `approval_required`, present the returned prompt and `approval_url` to the user. Poll the original operation after approval or denial. Approval is exact to one operation and is never inferred from an AI response.

## Credential classes

| Credential | Scope | Use |
|---|---|---|
| `core_mk_` | User account across its organizations; payer resolved per operation. | Trusted AI agent or harness using account MCP. |
| `core_sk_` | One project and spend grant. | Application code calling Core services. |

An authenticated agent can create a project key when a project needs it:

```sh
npx @core-so/login key create --project <project-name>
npx @core-so/login key run --project <project-name> -- <command>
```

## Related

- [Model router and project keys](https://docs.core.so/api-keys-and-inference.md)
- [Core Agent](https://docs.core.so/core-agent.md)

---

Canonical source: https://docs.core.so/publishing-supply.md

# Publishing tools

Use this document when adding a callable MCP tool to Core's catalog.

## Publish

Open [Build](https://build.core.so/account/build) and provide:

- a public HTTPS MCP endpoint;
- the tool exposed by `tools/list`;
- a payee reference;
- a flat price, or a metered price with a ceiling.

The endpoint must use public DNS, must not redirect, and must not contain credentials in its URL. Core calls `initialize` and `tools/list`, validates bounded response sizes, and records the discovered definition.

## Pinning

| Pin | Protects |
|---|---|
| Definition pin | Exact callable tool schema. |
| Content pin | Exact bytes of an installable artifact. |

Ingestion never silently replaces an existing definition pin. Publish a deliberate new version when the schema changes. Before any paid dispatch, Core compares the live definition to its pin.

## Dispatch eligibility

An endpoint that differs from its definition pin receives trust `0`, is suspended, and cannot dispatch. An unreachable endpoint is demoted through its trust score but remains distinct from schema drift. Receipt-backed reviews can affect ranking but cannot override suspension.

Publishing credentials are independently revocable. Their plaintext is returned once; Core stores only a digest, display prefix, and revocation state.

## Related

- [Tool store and rankings](https://docs.core.so/core-store.md)
- [Billing and credits](https://docs.core.so/billing-and-credits.md)