# How does an agent work with firm os for a firm?

> Where an agent reads about firm os, how it prepares a firm's install and follows it, and what only a person at the firm does.

firm os is a workspace for venture capital and private equity firms. It runs in the firm's own Cloudflare account, with an agent beside each person. Railblocks makes it. It is in closed beta with Railblocks' clients, and installs are by invite. This guide is all an agent needs to tell a firm what firm os would do for it, and to prepare its install.

## Who it is for

- **For:** an agent or assistant working for a person at a venture capital or private equity firm. It reads about firm os, says what firm os would do for the firm, or prepares the firm's install and follows it.
- **Not for:** acting without a person at the firm. A person signs in to Cloudflare and presses Allow. An agent never does.
- **Not for:** a firm without an invite. Its person asks for access on the [front page](https://firmos.railblocks.com/).
- **Not for:** working inside firm os once it is installed. Each person there has an agent of their own.

## Ways in

| Address | What it is for |
| --- | --- |
| `https://firmos.railblocks.com/index.md` | The front page's words as Markdown. `https://firmos.railblocks.com/` asked for with `Accept: text/markdown` answers the same |
| `https://firmos.railblocks.com/llms.txt` | What firm os is, its key facts, and every address here, in plain text |
| `https://firmos.railblocks.com/llms-full.txt` | Every docs page in one file |
| `https://firmos.railblocks.com/docs.md` | The docs, each page by its Markdown address |
| `https://firmos.railblocks.com/docs/{page}.md` | Each docs page as Markdown. A page asked for with `Accept: text/markdown` answers the same |
| `https://firmos.railblocks.com/install.md` | What installing asks for and does |
| `https://firmos.railblocks.com/openapi.json` | The install API, as OpenAPI 3.1: the two calls below |
| `https://firmos.railblocks.com/.well-known/api-catalog` | Where the install API's description and this guide are (RFC 9727) |
| `https://firmos.railblocks.com/.well-known/agent-skills/index.json` | The skills index (Agent Skills Discovery): one skill, `firm-os-install` |
| `https://firmos.railblocks.com/.well-known/agent-skills/firm-os-install/SKILL.md` | This guide as a skill, to keep |
| `https://firmos.railblocks.com/sitemap.xml` | Every page, for search engines |
| `https://firmos.railblocks.com/robots.txt` | What crawlers may read, and the Content Signals |

To act, an agent uses two more: `POST https://firmos.railblocks.com/plans` and `GET https://firmos.railblocks.com/installs/{id}/status`. The Install link a plan answers with is for a person.

## Ask about firm os

A person can give their assistant this line:

```
Read https://firmos.railblocks.com/llms.txt and tell me what firm os would do for our firm.
```

Answer from what llms.txt and the docs say, for that firm. Where they say nothing, say so.

## Prepare an install

### 1. Gather the plan

Ask the person for the firm's name, the email domains the firm owns, and the people to let in: each one's email, role, and whether they administer firm os. At least one is an admin, and 50 at most.

### 2. Post the plan

`POST https://firmos.railblocks.com/plans` with `content-type: application/json`. Any site may post it.

```json
{
  "firm": "Acme Capital",
  "about": "One line the firm's agents read.",
  "domains": ["acme.example"],
  "people": [
    { "name": "Ana", "email": "ana@acme.example", "role": "managing partner", "admin": true },
    { "name": "Ben", "email": "ben@outside.example", "role": "associate", "admin": false }
  ]
}
```

| Field | Rules |
| --- | --- |
| `firm` | Required, up to 60 characters, with letters or digits. It names the parts: `acme-capital` |
| `about` | Optional, up to 200 characters |
| `domains` | Optional: a list, or one comma-separated string. Anyone with an address there can sign in, so list only domains the firm owns |
| `people` | 50 at most, each email once. `name` defaults to the email and `role` to `associate`. At least one has `admin` set to `true` |

The install uses each person's email and admin flag. Names and roles stay with the plan until it is deleted. A plan is at most 64 KB, and one address may post 20 plans a minute.

A plan that passes answers `201`:

| Field | Meaning |
| --- | --- |
| `plan` | The plan's number, 22 characters. It is the install's ID once a person presses Allow |
| `install` | The Install link: `https://firmos.railblocks.com/start?plan=` and the number |
| `expiresInHours` | `24`: the plan waits a day for its Allow |

A refused plan answers `400`, `413` or `429` with a `problem` field: one sentence saying what to fix.

### 3. Hand the Install link to a person

Give the Install link to a person at the firm who is signed in to the Cloudflare account. They check who can sign in, press **Install with Cloudflare**, tick one account and press Allow. Picking the account, and **Try again** if a step stops, are theirs too.

### 4. Follow the install

`GET https://firmos.railblocks.com/installs/{id}/status`, with the plan's number as the ID. It answers `404` until the Allow, then:

| Field | Meaning |
| --- | --- |
| `status` | `running`, `done` or `failed` |
| `steps` | Each step's `name`, `title`, `state`, time in `ms`, and `detail`: what it made |
| `parts` | Each Cloudflare part on the page's plate: its `state` (`waiting`, `setting`, `set`, `lifting`, `gone` or `failed`), its `word`, and a `count` for the parts that come in numbers |
| `now` | The step running now |
| `address` | Where firm os opens, once `done` |
| `problem` | Why it stopped |
| `keyHeld` | Whether **Try again** can still carry on |

It also carries `id`, `kind`, `firm`, `account`, `made`, `planHeld`, `turn`, `readout`, `foot`, `drawing` (the plate in words), and `choose` while the person picks an account. An install takes about two minutes, so polling every few seconds is enough.

## Do not

- Never press **Install with Cloudflare**, Allow, or any button on a Cloudflare page.
- Never type Cloudflare sign-in details, passwords or email codes, and never ask a person for them.
- Never say firm os is open source or free. It is in closed beta with Railblocks' clients, and Cloudflare bills the firm for what runs in its account ([cost](https://firmos.railblocks.com/docs/cost)).
- Never invent a status or a feature. Pass on only what the status answers and what these pages say.
- Never use an address this guide doesn't list.

## Check it worked

- `GET https://firmos.railblocks.com/installs/{id}/status` answers `"status": "done"` and an `address`: where firm os opens.
- The person opens that address, gives their email and types the code Cloudflare sends. The first admin to sign in sees firm os set itself up for the firm.
- If it answers `"status": "failed"`, pass on its `problem`. When `keyHeld` is `true`, the person can press **Try again** on the install's page, `https://firmos.railblocks.com/installs/{id}`.

The install's page is also where the firm [removes firm os](https://firmos.railblocks.com/docs/remove).

Updated 2026-10-02.