# Quickstart

You'll make a Model that reads each email and says whether it needs a reply, call it from your code, and ask for one thing to get better.

It takes a few minutes of your time. Facet builds v1 in the background and emails you when it's live.

## Before you start

- A Facet account. Facet is invite-only for now: [join the waitlist](https://halfspacelabs.com/waitlist), and once you're invited, sign in at [facet.halfspacelabs.com](https://facet.halfspacelabs.com) with Google or GitHub.
- A coding agent: Claude Code, Cursor, VS Code, Codex or another MCP client.
- No card to build v1: every account gets a $15 free credit, once, for drafting, training and calls; see [Pricing](/docs/pricing).

## 1. Connect your coding agent

You make a Model from your coding agent, where it can read your code. In the web app, **New model** opens Claude Code, Codex or Cursor on a prompt that connects Facet for you, or shows how to connect any agent under **Connect Facet to your agent yourself**. In Claude Code, you can also install the plugin:

```sh
claude plugin marketplace add halfspacelabs/facet-plugins && claude plugin install facet@facet
```

Then sign in once:

1. Restart Claude Code so it loads the plugin.
2. Run `/mcp`, choose **facet**, then **Authenticate**.
3. Sign in in the browser tab that opens, with the email Facet invited.

When it worked, `/mcp` lists **facet** as connected.

Other agents add `https://facet.halfspacelabs.com/mcp` as an MCP server; see [Use Facet from an agent](/docs/agents).

## 2. Ask for a Model

In your repo, run `/facet:find` to find the LLM calls a small model could take over, or say what the task is. A sentence is enough:

> For each email, say whether it needs a reply, who it's from and what they ask. Newsletters and receipts never need one.

In Cursor, VS Code or another agent, use **Replace a call in your code** on **New model**: it opens your agent on a prompt that finds the call, collects real inputs, and makes the Model once you say yes.

To try Facet before you pick a call, **New model** in your Personal workspace also has a template on the receipts sample: **Build it** drafts the Model in the web app, where you review and approve it.

Your agent reads the call it replaces and real inputs from your code, and shows you the rows before anything leaves your machine. Then Facet drafts the Model. Your agent shows you the draft:

- **Name:** what you call it by, such as `reply-check`.
- **Reads and returns:** the shape of an input and of an answer.
- **Evals:** plain statements of what a good answer does, each with examples. See [Write good evals](/docs/evals).
- **Quote:** the most v1 can cost.

Ask for any change in plain words, and Facet redrafts it. Nothing is made until you say yes.

## 3. Approve the quote

Your agent shows the most v1 can cost and what it typically costs. Nothing is charged past that cap, and nothing starts until you say yes. You can also start it from the Model's Overview in the web app.

Facet then builds v1 on its own:

1. It writes more examples for each eval.
2. It trains a small model on them.
3. It checks the result against hidden examples, ones only Facet's checks read, so the score is honest.

You can close your agent; Facet emails you when v1 is live. The Model's Overview then shows its score on each eval, ready to try. Until then, calls to the Model answer `409 model_not_ready`.

## 4. Call it

Make an API key under **Settings, Keys**. Copy your serving URL from the **Code** view of the Model's Overview; it ends in `/v1`. Put both in your app's environment:

```sh
export FACET_BASE_URL="<your serving URL>"
export FACET_API_KEY="fct_..."
```

Then call the Model by name:

```python
import os
from openai import OpenAI

client = OpenAI(base_url=os.environ["FACET_BASE_URL"], api_key=os.environ["FACET_API_KEY"])
reply = client.chat.completions.create(
    model="reply-check",
    messages=[{"role": "user", "content": "Hi Maya, can you send the Q3 numbers by Friday? Thanks, Dev"}],
)
print(reply.choices[0].message.content)
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: process.env.FACET_BASE_URL, apiKey: process.env.FACET_API_KEY });
const reply = await client.chat.completions.create({
  model: "reply-check",
  messages: [{ role: "user", content: "Hi Maya, can you send the Q3 numbers by Friday? Thanks, Dev" }],
});
console.log(reply.choices[0].message.content);
```

```sh
curl "$FACET_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FACET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "reply-check", "messages": [{"role": "user", "content": "Hi Maya, can you send the Q3 numbers by Friday? Thanks, Dev"}]}'
```

The answer comes back in the shape the Model returns:

```json
{"needs_reply": true, "from": "Dev", "ask": "Send the Q3 numbers by Friday"}
```

## 5. Ask for it to get better

When an answer is wrong, tell your coding agent what should be different, in plain words: "an ask inside a forwarded thread still needs a reply". Add the inputs it got wrong if you have them.

Facet turns that into an eval, measures how often today's version misses it, and quotes the fix. Nothing is spent until you approve the quote.

The fix goes live when its evals pass and nothing the live version gets right breaks. Every caller gets it on their next call. Any change rolls back in one step. See [Make a Model better](/docs/improve).

## Troubleshooting

| What you see | Why | What to do |
|---|---|---|
| A waitlist form instead of sign-in | That email isn't invited yet | [Join the waitlist](https://halfspacelabs.com/waitlist), or sign in with the email your team invited |
| `/mcp` doesn't list **facet** | Claude Code hasn't loaded the plugin | Restart Claude Code, then run `/mcp` again |
| `409 model_not_ready` | v1 is still being built | Wait for the email, or watch the Model's Overview |
| `401 invalid_api_key` | The key is missing, revoked or mistyped | Check `FACET_API_KEY`, or make a new key under **Settings, Keys** |
| `404 model_not_found` | The name is wrong, or the key is limited to another Model | Copy the name from the Model's Overview |

Every other error is in [Errors](/docs/errors).

## Next steps

- [Write good evals](/docs/evals): the most useful ten minutes you'll spend on a Model
- [Call a Model](/docs/call): parameters, pinning a version, streaming
- [Use Facet from an agent](/docs/agents): every tool your agent can use