Docs

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.
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.

{
  "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).
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.

Updated 2026-10-02This page as Markdown