# Blue Leaf platform docs

The reference for building on Blue Leaf: agents, tools, files, long jobs, runners and secrets. This file is the source of the [Docs](https://www.blle.co/services/docs) page and is always current; agents can read it at https://www.blle.co/docs.md.

## Getting started

Everything here is scoped to your account and reachable three ways: the web UI, plain HTTP with your API key, and MCP for AI clients such as Claude.

These docs are also available as one Markdown file at https://www.blle.co/docs.md, always current. Point your agents at it so they work from the latest reference.

### Connection

| | |
|---|---|
| **API key** | On your [Account](/users/view) page. |
| **Auth** | A browser session in the UI, or `Authorization: Bearer <API_KEY>` for everything outside it. Both scope the request to your user. |
| `api.blle.co` | Runs things: agents, the MCP server, tools, files, jobs, runners and secrets. |
| `www.blle.co` | Manages things: creating and editing agents, schedules, file share links. |
| **MCP endpoint** | `https://api.blle.co/mcp` (Streamable HTTP transport, stateless) |

### Connecting Claude

```bash
claude mcp add --transport http blle https://api.blle.co/mcp
```

Claude Code and Claude Desktop sign in with OAuth 2.0 (PKCE) and open the browser for it. For headless or script use, send `Authorization: Bearer <API_KEY>` directly against `https://api.blle.co/mcp`.

## Agents

An agent is a versioned prompt plus a JSON settings block naming a provider, a model, and the tools it may reach. Once saved it is addressable by UUID: from the UI, the HTTP API, a cron [schedule](#schedules), or as an OpenAI-compatible model. Every run it makes is recorded. Build and edit them on [Agents](/services/chatbot).

### Endpoints

Running agents, on `api.blle.co`:

| Method | Path | Purpose |
|---|---|---|
| POST | `/agent/stream` | Server-Sent Events stream of the run. Events arrive as `{"type": "content", "content": "..."}`. Also accepts `multipart/form-data` to attach a file to the prompt. |
| POST | `/agent/run` | Synchronous. Blocks until the run finishes, returns `{response}`. Best for short interactive calls. |
| POST | `/agent/runs` | Asynchronous. Returns `202 {executionId}` plus a `Location` header immediately; the run continues server-side. |
| GET | `/agent/runs/:id` | Poll a run: `status`, `response`, and the full event list. A run cut short by a platform restart ends as `failed` with `error` "Interrupted by restart"; start it again. |
| GET | `/agent/runs/:id/events` | Attach an SSE stream to a run already in flight. |
| POST | `/agent/runs/:id/cancel` | Abort an in-flight run. The execution row is marked `failed`. |
| GET | `/v1/models` | OpenAI-compatible model list: one entry per agent you own, id `agent:<uuid>`. |
| POST | `/v1/chat/completions` | OpenAI-compatible chat completions against `model: "agent:<uuid>"`. Lets any OpenAI client talk to an agent unmodified. |

Managing agents, on `www.blle.co`:

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/agents` | Latest version of every agent you own. |
| POST | `/api/agents` | `action=add` (`name`, `prompt` required, `settings` optional JSON) · `action=edit` (`agent_uuid`, saves a new version) · `action=delete` (`id`) · `action=history` (`uuid`) · `action=executions` (`agent_id`, `execution_id`, `status`, `limit`) |

### Agents & versioning

- **Files:** each agent is a folder in your files, `/workspace/agents/<folder>/`. `AGENT.md` is the prompt and `agent.json` the settings. Agents (and you) can edit those files directly; the next run uses them.
- **Prompt:** the agent's role and instructions. Markdown headers keep long prompts navigable.
- **Settings:** JSON, see the reference below. Secrets go in by name only: `"apiKey": "OPENAI_API_KEY"`, and in another MCP server's headers `"Authorization": "Bearer {{secret:NAME}}"`. Blue Leaf's own MCP server needs no header: the agent reaches it as you.
- **Versioning:** every save keeps the previous files in the folder's `.versions/`. History and one-click restore live behind the clock icon on the [Agents](/services/chatbot) table.
- **UUID:** stable across versions. It is what `agentId` means everywhere on this page, so callers never have to track versions.
- **An edit saves a whole new version** from exactly what you send; only the favorite flag carries over. Through the API that means sending the complete `prompt` and `settings` every time: fields you leave out come back empty on the new version.

### Settings reference

| Setting | Meaning |
|---|---|
| `provider` | `claude` · `openai` · `gemini` · `openai-compatible`. Defaults to `claude`. |
| `model` | Provider model id, e.g. `claude-sonnet-4-6`. |
| `apiKey` | The *name* of a row in your [secrets manager](/services/secrets) (e.g. `OPENAI_API_KEY`), never a raw key. The server decrypts it at request time. Required. |
| `temperature` | Sampling temperature. |
| `maxTokens` | Response cap. |
| `thinkingBudget` | Extended-thinking token budget, for models that support it. |
| `mcpServers` | MCP servers the agent may call, keyed by name. Point one at your own [MCP server](#tools-mcp) (`/mcp`, or `/mcp/toolset/<id>` for a [toolset](#toolsets)) to give an agent your tool library; no API key needed. To limit which tools it sees, add `"tool_configuration": {"allowed_tools": [...]}` inside that server entry. |
| `responseSchema` | A JSON Schema. The agent then answers in a single call with JSON that matches it: `/agent/run` returns the object as `response`. Schema agents have no tools, so it can't be combined with `mcpServers`. `temperature` defaults to 0. Suited to steps a workflow tool hands off, like classifying, extracting or turning a search query into filters. |
| `baseURL` | Required for `openai-compatible`: the endpoint to send to. |

```json
{
  "provider": "claude",
  "model": "claude-sonnet-4-6",
  "apiKey": "ANTHROPIC_API_KEY",
  "temperature": 0.7,
  "maxTokens": 1000,
  "mcpServers": {
    "blle": { "type": "http", "url": "https://api.blle.co/mcp" }
  }
}
```

### Execution model

- Pick by shape of the call: **stream** for a UI, **run** for something that finishes in seconds, **runs** for anything that might not.
- `/agent/run` holds the connection open. That is fine until it isn't: long calls fight every timeout in the path, which is what `/agent/runs` plus polling exists to avoid.
- Add `format: "json"` to `run` or `runs` for structured output. The synchronous call returns it parsed, fences stripped; the poll returns the agent's *raw* response, so strip fences yourself.
- Pass a `sessionId` to continue a conversation: runs sharing one see the prior turns. Omit it and each run starts clean. `metadata` carries any extra context you want on the record.
- Every run (UI, API, or schedule) writes an execution row. Token spend and failures show up on [Activity](/services/chatbot/reports).

### Embedding a chat agent

A [website chat widget](/services/chatbot#widgets) is an agent wrapped in a public widget. It carries its own client id, so the page it sits on never sees your API key. Widgets are listed under the agents on the Agents page; copy the snippet from a widget's code button and paste it anywhere in the `<body>` of your site.

```html
<chat-bot client-id="YOUR_CLIENT_ID"></chat-bot>
<script type="module" src="https://blle.s3.amazonaws.com/chatbot/index.js"></script>
```

### Calling an agent from HTTP

Use your API key as the Bearer token. `agentId` is the agent's UUID: copy it from the [Agents](/services/chatbot) table.

**Synchronous**

```bash
curl -X POST https://api.blle.co/agent/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<uuid>", "prompt": "Summarize the inbox"}'
```

**Asynchronous:** start, then poll until `status` is `completed` or `failed`.

```bash
curl -X POST https://api.blle.co/agent/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<uuid>", "prompt": "Research and write the weekly brief"}'

curl https://api.blle.co/agent/runs/<executionId> -H "Authorization: Bearer YOUR_API_KEY"
```

**Streaming** (SSE)

```bash
curl -N -X POST https://api.blle.co/agent/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<uuid>", "prompt": "Hello", "sessionId": "<optional>"}'
```

**As an OpenAI model**

```bash
curl -X POST https://api.blle.co/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "agent:<uuid>", "messages": [{"role": "user", "content": "Hello"}]}'
```

**Create an agent**

```bash
curl -X POST https://www.blle.co/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "add", "name": "Brief writer", "prompt": "You are...", "settings": "{\"provider\":\"claude\"}"}'
```

> **Secrets, not keys.** Provider credentials live in the [secrets manager](#secrets) and agent settings reference them by name. A raw key pasted into an agent is stored in every version of that agent from then on.

## Tools & MCP

Blue Leaf runs its own Model Context Protocol server so AI clients (Claude, workflow tools, your own agents) can discover and run tools, read documents, and use encrypted secrets. Tools are stored as code and run in a secure Deno sandbox. Your library is listed on [Tools](/services/mcp/tools).

### Endpoints

| Method | Path | Purpose |
|---|---|---|
| POST | `/mcp` | Main MCP endpoint (Streamable HTTP). Per-request server, tools scoped to the user. |
| GET | `/mcp/health` | Health check. |
| POST | `/tools/run` | Direct HTTP execution of a tool by name. Authenticated with your API key. Optional `timeout` (ms, max 300000) and `"async": true` to answer at once and run in the background. |
| OAUTH | `/authorize` · `/token` | OAuth 2.0 Authorization Code + PKCE for Claude Desktop / CLI. |

Tools can also run from outside services or on a schedule: see [Long jobs, schedules & triggers](#long-jobs-schedules-triggers).

### Built-in tools

The MCP server exposes these to any connected client or agent, alongside your own tools.

| Tool | What it does |
|---|---|
| `Search_Tools` | Search your tools by keyword. Returns id, name, description. |
| `Get_Tools` | Fetch one or more tools by name, including the full source code, read from the tool's file. |
| `Run_tool` | Execute a tool by name with params. Default 60s timeout, max 300s. |
| `Create_Tool` | Create a new tool (name, description, JS/TS code). The code is saved to `/workspace/lib/tools/<name>.ts`. Owned by the calling user. |
| `Update_Tool` | Update a tool by id. You can only update your own tools. The code it replaces is kept in `/workspace/lib/tools/.versions/<name>/`. |
| `Delete_Tool` | Delete a tool by id. You can only delete your own tools. |
| `Execute_Code` | Run ad-hoc JS/TS in the Deno sandbox for one-off tasks, including reading and writing your files through `context.fs`. Streams console output. |
| `Get_Resource` | Read a document from `/workspace/docs` by key (its path there without the extension). See [Documents as MCP resources](#documents-as-mcp-resources). |
| `Invoke_Agent` | Run one of your agents as a sub-agent and return its reply. Runs on the server, not in the sandbox, with no tool timeout; chains stop at 3 levels. |
| `Run_On_Runner` | Run a command on your account's [runner](#runners) (ffmpeg, renders, Python) and wait up to an hour for the result. |
| `Show_UI` | Show an interactive page you built under `/workspace/ui/<name>/` inline in the chat. The page can call the tools listed in that folder's `ui.json` (through `UI_Call`). |
| `Manage_Secrets` | list / set / delete encrypted secrets scoped to your user. |

### Writing a tool

- A tool is a module that exports `async function run(context)`. Params arrive on `context` (`const { foo } = context`); `return` outputs the result; `console.log` is captured as log events.
- Tools run inside a shared **Deno sandbox** with `fetch()` available. Import npm packages from `https://esm.sh/<package>@<major>`.
- `context.fs` reads and writes your `/workspace` files (read / write / list / stat / exists / delete / move).
- Default timeout **60s**, max **300s**. For longer work see [Long jobs](#long-jobs-schedules-triggers); work that needs real programs goes to a [runner](#runners).
- All your secrets are injected into every run as `context.secrets` and as `Deno.env` variables.
- Tools can persist a new secret (e.g. refreshed OAuth tokens) via `await context.saveSecret(name, value)`.
- When an agent calls a tool, `context.caller` names it (`agentId`, `agentName`, `folder`, `executionId`); it is `null` for a person or an outside caller.

### Deno sandbox

`Execute_Code` and every tool run inside one Deno sandbox. Each run is fresh — variables do not survive to the next run. Your `/workspace` files and secrets do persist, so write anything you want to keep to disk. In your code, a returned value is the run's result; `console.log` streams alongside it as log events, so it is a side channel, not the answer.

- **Imports are ESM only.** `npm:` imports resolve to a small pre-installed set; anything else comes from esm.sh with the major pinned: `import OpenAI from "https://esm.sh/openai@4"`. Prefer built-in Web APIs (`fetch`, `crypto.randomUUID`, `atob`) over a small package. Shared TypeScript you keep in `/workspace/lib` imports by path: `import { clients } from "lib/clients.ts"`.
- **A `lib/...` import line fails an `Execute_Code` run before it starts** — the host resolves any `import ... from "lib/..."` in the source, even one inside a string, so keep such lines out of code you generate at runtime.
- **Files:** the async `Deno.*` filesystem calls work on your `/workspace` (the sync variants throw), as do the explicit `context.fs` verbs — `read` / `write` / `list` / `stat` / `move` / `delete`. There is no `mkdir`: writing `/workspace/a/b.txt` creates the folder. Paths must be absolute and start with `/workspace/`. A single write is capped at **10 MB** — larger payloads go to S3 or another store. Text crosses as UTF-8 and binary as base64, so don't base64-encode text yourself.
- **Secrets** are in `Deno.env` for the run, so an SDK that reads its own key from the environment just works; a refreshed token is saved back with `await context.saveSecret(name, value)`.
- **No shell and no native modules** (FFI is denied). Anything needing a real program goes to a [runner](#runners); in the sandbox, reach for pure-JS or WASM packages.

### Running a tool from HTTP

Use your API key as the Bearer token. Tools are scoped to your user account.

```bash
curl -X POST https://api.blle.co/tools/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toolName": "my_tool", "params": {"limit": "5"}}'
```

### Toolsets

A toolset is a named list of tools with its own MCP URL, `https://api.blle.co/mcp/toolset/<id>`. A client or agent on that URL sees only those tools, none of the built-in management tools. Use one for any agent that talks to the public: however a visitor steers it, it can only call what the list names. Create and edit them at the top of the [Tools](/services/mcp/tools#toolsets) page.

- Point the agent's MCP server entry at the toolset URL instead of `/mcp`. An agent on Blue Leaf needs no header; an outside client sends your API key as the Bearer token.
- Toolset tools take any params: list them in each tool's description so the model fills them in.
- On chat-widget runs, tools get the visitor as `context.visitor`: the page's cookies (`context.visitor.cookies`) and URL (`context.visitor.currentUrl`). The platform sets it, so a model can't substitute another visitor. Each site's tools pick the cookie they need.
- Tools still run as you, with your secrets, so keep a public toolset to tools meant for visitors.

> **Tools are managed by agents, not the UI.** The [Tools](/services/mcp/tools) page is a read-only listing. To add, update, or delete tools, ask an agent with MCP access: it calls `Create_Tool` / `Update_Tool` / `Delete_Tool` on your behalf.

## Files & resources

Your workspace (`/workspace/...`) is one file tree shared by the [Files](/services/mcp/files) page, agents, tools (`context.fs`) and the endpoints below, so an agent can drop an artifact and a script can pull it out, or the other way round. Everything is private except `/workspace/public/`, which anyone with the link can open.

### Endpoints

| Method | Path | Purpose |
|---|---|---|
| POST | `/mcp/files/upload` | Upload one or more files (multipart). |
| GET | `/mcp/files/download` | Download a file by path. |
| GET | `/mcp/files/list` | List entries under a directory with size + mtime. |
| POST | `/mcp/files/upload-url` · `/download-url` | Signed S3 URL to `PUT` (up to 5 GB) or `GET` one file directly, for files above the 10 MB the endpoints above buffer. |
| POST | `/mcp/files/delete` | Delete a file by path. |
| POST | `www.blle.co/services/mcp/share-file` | Public download link to a file, expiring in 1–30 days: `{path, days}` → `share.url`. List links with `GET …/share-links?path=`, revoke with `POST …/unshare-file {id}`. |

### Uploading & downloading

Multipart uploads accept `file` (single) or `files[]` (multiple), plus an optional `prefix` field (defaults to `/workspace/uploads`).

**Upload**

```bash
curl -X POST https://api.blle.co/mcp/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "prefix=/workspace/inbox" \
  -F "file=@./report.pdf"
```

**Download**

```bash
curl -OJ https://api.blle.co/mcp/files/download?path=/workspace/inbox/report.pdf \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The per-file limit on these two is **10 MB**; use the signed URLs above for anything bigger. Paths must be absolute and start with `/workspace`.

### Documents as MCP resources

Markdown and text files under `/workspace/docs/` are MCP resources: agents read and edit them as files, and MCP clients read them as resources. Keep anything you don't want shared with MCP clients outside that folder.

- URI template: `docs://documents/{key}`, where the key is the path under `/workspace/docs/` without the extension (e.g. `support/policies/returns` → `/workspace/docs/support/policies/returns.md`).
- Agents read one with the `Get_Resource` tool and the same key.
- MIME type: `text/markdown`.
- Clients list them via the MCP `resources/list` request and read them via `resources/read`.

## Long jobs, schedules & triggers

Agents can work for as long as a job takes. A run belongs to the platform, not your browser: close the chat or switch threads and the reply is waiting when you come back. If the platform restarts mid-run, the run ends as failed ("Interrupted by restart"); run it again. Tools are the short pieces: each tool call has a 5-minute limit.

### Long-running work

- **Long commands** (renders, ffmpeg, Python, headless Chrome): the `Run_On_Runner` tool waits up to an hour for a job on your [runner](#runners).
- **Work for another agent:** `Invoke_Agent` runs one of your agents as a sub-agent, with no time limit, and returns its reply.
- **Big batches:** the agent splits the work and runs a tool once per chunk.
- **Recurring work:** a [schedule](#schedules).
- **From outside:** `POST /agent/runs` starts an agent and answers `202` at once; poll `GET /agent/runs/<executionId>` for the reply. To start a tool without waiting, add `"async": true` to `POST /tools/run`; it answers `202` and the outcome is in the tool's history.

```bash
curl -X POST https://api.blle.co/tools/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toolName": "my_tool", "params": {...}, "timeout": 300000, "async": true}'
```

> **Using a workflow tool?** Let n8n, Zapier or Make do the plumbing: triggers, app connectors, timed sequences and routing. Call Blue Leaf for the steps that need an agent: `/agent/run` for a quick answer (structured JSON if the agent has a response schema), or `/agent/runs` for a long run.

### Schedules

A [schedule](/services/chatbot/schedules) sends one fixed prompt to one agent on a cron interval: the way a recurring report or a nightly sweep gets built.

- **Cron format:** `minute hour day month weekday`
- **Timezone:** `America/Chicago`
- Each run creates an execution record, same as an API call, visible on [Activity](/services/chatbot/reports) or through `action=executions`.
- **From HTTP:** `POST www.blle.co/services/chatbot/schedules` with your API key and form fields `action=add`, `agent_id` (the agent's UUID), `name`, `prompt`, `cron_expression` and `enabled=1`. Pausing, editing and deleting are on the Schedules page.

### Triggers from outside services

To react to an outside event (a form, a store order, a Stripe event), let a workflow tool receive the webhook, then call Blue Leaf with your API key: `POST https://api.blle.co/tools/run` for a tool, or `/agent/runs` for an agent. Blue Leaf itself has no unauthenticated way in.

```bash
curl -X POST https://api.blle.co/tools/run \
  -H "Authorization: Bearer $BLLE_API_KEY" -H "Content-Type: application/json" \
  -d '{"toolName": "my_tool", "params": {"order_id": 12345}}'
```

## Runners

The Deno sandbox is for quick API and data work. Jobs that need real programs (ffmpeg, headless Chrome, video rendering, speech-to-text) run on a **runner**: a machine connected to your account that runs each command in a locked-down sandbox. The runner downloads the job's inputs from your `/workspace`, runs the command and uploads the outputs back.

### Getting a runner

Runners are set up per account; ask us to add one. It can run on your own Linux machine (it only makes an outbound connection, so no ports are opened) or we can host it. Each runner only takes jobs for its own account.

### Running a job

Agents call the `Run_On_Runner` tool, which waits for the job and returns its result. `command` is the program and its arguments; `inputs` are `/workspace` files (or folders ending in `/`) copied into the job; `outputs` are file patterns to keep, saved under `output_dir`.

```json
{
  "command": ["ffmpeg", "-i", "talk.mp4", "-vn", "talk.mp3"],
  "inputs": ["/workspace/artifacts/video/talk.mp4"],
  "outputs": ["*.mp3"],
  "output_dir": "/workspace/audio",
  "timeout": 600
}
```

- Timeout up to 1 hour; files up to 5 GB each; each runner takes 2 jobs at a time and queues the rest.
- The agent waits without tying up the tool sandbox, and its reply comes back when the job is done. You don't have to keep the chat open.
- From another MCP client, call `Run_On_Runner` over MCP like any other tool.
- If no runner is connected to your account, the call fails right away. A job in progress when the platform restarts is lost; run it again.

## Secrets

One encrypted store for every credential on the platform. A secret is a name and a value; everything else here is about getting that value to the thing that needs it (a tool, an agent, a process on your laptop) without the value itself being written down anywhere else. Nothing that consumes a secret stores it: they all reference the name and resolve it at run time. Manage them on [Secrets](/services/secrets).

### Secrets, projects & mappings

- A **secret** is a name, an encrypted value, and an optional description. The value can be a plain string or a JSON object.
- A **project** is just a label. It has no row of its own: it exists as long as some mapping names it.
- A **mapping** binds an environment variable to a secret within a project. The variable name is independent of the secret name, so one secret can arrive as `DB_PASSWORD` in one project and `POSTGRES_PASSWORD` in another. Names are upper-cased when saved.
- A mapping can also carry a **key**. With one set, the secret is parsed as JSON and only that key's value is exported, so a single secret holding `{"host": "...", "user": "...", "password": "..."}` can feed three separate environment variables. Without one, the whole value is exported as-is.

Manage secrets on [All Secrets](/services/secrets); wire up the mappings on [Projects](/services/secrets/projects).

### What reads them

| Reader | How |
|---|---|
| [Tools](#tools-mcp) | **All** of your secrets are injected into every tool run, as `context.secrets` and as ordinary `Deno.env` variables, so an SDK that picks its own key out of the environment just works. No project mapping needed; this path ignores projects entirely. |
| [Agents](#agents) | An agent's `settings.apiKey` holds the *name* of a secret, never a key. It is required: an agent whose secret is missing or misnamed fails the run with a 400 rather than falling back to a platform key. |
| The CLI | Exports one project's mappings into a process at launch. This is the only consumer that uses projects. |
| HTTP | Anything else: `GET /secrets/:project` hands back a ready-made env object. |

### Endpoints

On `api.blle.co`. Every route resolves your API key to your user and only ever touches that user's secrets.

| Method | Path | Purpose |
|---|---|---|
| GET | `/secrets` | Project names that have at least one mapping. Returns a plain array. |
| GET | `/secrets/:project` | That project's environment as `{VAR: value}`, decrypted and with JSON keys resolved. `404` if the project has no mappings. |
| POST | `/secrets/manage` | Create or update: `name` required, plus `value` and `description`. Sending an empty `value` updates only the description; it does not blank the secret. |
| DELETE | `/secrets/manage/:name` | Delete by name. |

Three refusals worth coding for: `403` when the name is already taken by another user's secret (names are checked across all users, so a create can be refused by a secret you cannot see), `409` on delete when project mappings still point at the secret (the response lists them; unmap first), and `404` on delete when the name doesn't exist.

### What the API can and can't do

The API manages **values**: create, rotate, describe, delete. It does not manage **mappings**: adding, editing, or removing a project mapping is a signed-in action on the [Projects](/services/secrets/projects) page. So a rotation script can replace a value and every project already pointing at it picks up the new one on next read; standing up a *new* project still needs a visit there.

### The CLI

```bash
export SECRETS_API_KEY=<your api key>
secrets run --project <name> -- <command> [args...]
```

- Fetches the project's environment, adds it to the current environment, and then **replaces itself** with your command. There is no wrapper process and no temp file: the values exist only in the memory of the process you were launching anyway.
- Fetched values **override** variables already set in your shell.
- An unknown or unmapped project **fails the command**: the API answers `404` and the CLI exits rather than launching with a thinner environment than you expected.
- It presents a browser-like TLS fingerprint to get past the edge. A response that arrives as HTML is reported as `blocked by Cloudflare challenge`: that's the edge, not your key.
- Download it from the [All Secrets](/services/secrets) page: macOS (Apple Silicon), Linux x64, Linux ARM.

### Encryption

- Values are encrypted at rest with **AES-256-GCM** and stored as `iv:authTag:ciphertext`. Encryption happens server-side on write; you always send plaintext.
- A stored value that doesn't match that shape is returned as-is rather than failing, which is how older plaintext rows still read. Don't take a successful read as proof a given row was ever encrypted.
- Reads decrypt in the API process. Values are never rendered back into the UI: the list shows names, descriptions, and how many projects use each one.

### From HTTP

**Rotate a value**

```bash
curl -X POST https://api.blle.co/secrets/manage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "OPENAI_API_KEY", "value": "sk-...", "description": "rotated 2026-09"}'
```

**Pull a project's environment**

```bash
curl https://api.blle.co/secrets/<project> \
  -H "Authorization: Bearer YOUR_API_KEY"

# {"DB_HOST":"...","DB_PASSWORD":"..."}
```

**Delete one** (unmap it first, or this answers `409`)

```bash
curl -X DELETE https://api.blle.co/secrets/manage/<name> \
  -H "Authorization: Bearer YOUR_API_KEY"
```

> **Every tool run sees every secret.** Injection is not scoped by project or by tool, so a secret in this store is readable by any tool you run. That is what makes tools convenient to write, and it is the reason to keep credentials you would not hand to an agent out of here entirely.
