# Build with Pit Officer Pit Officer runs the OpenPit risk engine behind a local operator panel, REST API and MCP server. This guide is an entry point for people and coding agents. Use the running instance's API and available connections when generating code or choosing a trading connector. ## Choose the integration - **Operate risk or try a workflow:** use the panel to configure accounts, instruments, data and policies, and inspect decisions. - **Connect your application:** use Officer's REST API. You do not need to embed the engine or build an operator panel yourself. - **Connect an AI agent:** use MCP with a deliberately limited set of tools. - **Embed the engine:** use the [OpenPit SDK](https://openpit.dev/llms.txt) instead. Its [wiki](https://wiki.openpit.dev/llms.txt) explains the engine lifecycle; SDK installation commands do not install Officer. ## Start a local instance Use the public Docker image to run Officer locally. Install Docker using the [official installation guide](https://docs.docker.com/get-started/get-docker/) and start Docker Desktop. Open PowerShell on Windows or Terminal on macOS/Linux. Paste this single command and press Enter: ```sh docker run -d --name pit-officer --restart unless-stopped -p 127.0.0.1:8787:8787 -v pit-officer-data:/data ghcr.io/openpitkit/officer ``` Docker downloads the image if needed and starts Officer in the background. Wait for the first startup, then open [the local panel](http://127.0.0.1:8787). Bookmark this address to return later. The command publishes only the loopback address and stores the database in the named volume `pit-officer-data` under `/data`. It does not require a source checkout, local build or Compose file. To open the panel from a command line on the same computer, use the command for your operating system. These launch the host's browser, not a browser inside the container: ```powershell # Windows PowerShell Start-Process http://127.0.0.1:8787 ``` ```sh # macOS open http://127.0.0.1:8787 # Linux desktop xdg-open http://127.0.0.1:8787 ``` If you stopped Officer, start the existing container instead of repeating the first-install command: ```sh docker start pit-officer ``` Keep the named volume when stopping or replacing the container. Do not delete it to resolve a container-name conflict. The panel link requires a running service on this computer; it does not start Officer by itself. For a native process, follow the [build prerequisites and commands](https://github.com/openpitkit/officer/blob/main/README.md#build). Native builds use Go, Node/npm, Python 3, a C toolchain with cgo enabled and Just. The native server uses an OS-assigned port; use its reported address instead of assuming the Compose port. For source builds or custom deployment, use the repository's Dockerfile and Compose instructions in the same build guide. These are the engineering path, separate from the published-image quickstart above. ## Give your agent the actual API The running instance serves its exact OpenAPI schema at `/api/openapi.yaml` and a browser reference at `/docs`. The reference viewer uses a public Swagger UI CDN; the schema itself is embedded and works without that CDN. For a source review, use the [source schema](https://raw.githubusercontent.com/openpitkit/officer/main/httpapi/openapi.yaml), but use the running instance's schema when generating requests. Read the [API notes](https://raw.githubusercontent.com/openpitkit/officer/main/docs/api.md). Application clients use `/api/v1`. The `/app/api/v1` mirror is for the panel and stamps a different audit source. Money and quantity values are exact decimal strings. Preserve these strings rather than converting them through binary floating-point numbers. Handle both documented error shapes. ## Receive market prices automatically Configure a price source and subscribe to the required instruments in the panel. Officer receives quotes from the source and supplies them to OpenPit. Use the panel's quote timestamps, source status and diagnostics to inspect availability and freshness. Built-in price-source adapters include Interactive Brokers, Binance, Kraken, Coinbase, Alpaca, OKX, Bybit, OANDA and Finnhub. A custom source can supply data from your own infrastructure. Provider credentials, data entitlements and instrument subscriptions still apply. Quote adapters and trading connectors are separate: receiving a provider's prices does not itself enable sending orders to that provider. ## Inspect the first decision Use a local instance with no trading connection configured for the first step. Create an account and instrument, supply any balances and FX data required by the selected policies, configure the instrument's market data and those policies, and generate or import an active signing key. Signing is enabled by default and a fresh database has no active key. Submit a candidate order, inspect its accept/reject decision, and compare it with the recorded order-decision audit entry. A dry-run is a different operation: it leaves order state unchanged and does not create an order-decision audit record. Do not test a dry-run by expecting that record. Read the instance schema for the exact operation and request body; this guide does not replace that schema. ## MCP connection and permissions `serve` exposes streamable HTTP MCP at `/mcp` on the same reported base URL. The binary's `mcp` subcommand provides stdio transport for clients that launch a local server. See the [configuration reference](https://raw.githubusercontent.com/openpitkit/officer/main/docs/configuration.md) for flags, runtime and database paths. Do not assume a particular client's configuration-file format or launch a second process against a running store without checking the deployment instructions. Discover the actual tool catalog. A catalogued but unimplemented tool is not callable. Non-mutating tools are enabled by default; each mutating tool requires operator opt-in by name. Account block and unblock are not MCP tools. Enable only what the intended workflow needs and verify that disabled mutations are refused. ## Sending orders and reporting executions Built-in trading connections include Interactive Brokers (TWS / IB Gateway), Binance, Alpaca and eToro. Configure a connection in the panel to send approved orders and receive execution updates into Officer's accounting. This is a separate operation from evaluating an order. Confirm provider, instrument, paper/live and account support in the running instance before generating an integration. In an approval-only integration, the external executor must verify a signed acceptance bound to the exact order before sending it. Unsigned mode exists; not every validation error is a signed risk decision. An independent path with its own broker credentials can bypass an external approval gate. Keep fills and account state current through the documented execution-report flow. Post-trade reporting alone cannot stop a trade. Confirmation, execution reports and cancellation govern reservations; they do not simply expire on a timer. Blocking accounts or groups stops new risk approvals, not existing orders at a venue, and does not imply cancel-all or liquidation. ## Deployment and evidence boundaries The panel, REST and HTTP MCP have no built-in authentication. Native access is loopback by default; supply an access boundary before exposing it elsewhere. Stored-secret encryption requires operator configuration and is not enabled unconditionally. Follow the configuration reference for master-key handling. The ordinary audit API cannot edit individual records. Backup restoration and service-data reset can replace or remove history, so the journal is not immutable external archival. Reproducing a risk decision requires the same complete account, policy, position, reservation and market-data state. Realized P&L depends on reported executions and configured FX data. Risk barriers do not guarantee against losses. ## Copy this brief into your coding agent ```text Help me build a local integration with Pit Officer. Read https://officer.openpit.dev/llms.txt and follow its integration guide. First establish my actual Officer service URL, target workflow and whether I need the operator panel, REST API or MCP. Read /api/openapi.yaml from that instance and the matching API/configuration docs. Use the actual tool catalog for MCP. Do not invent endpoints, fields, tool names, installer commands or supported trading connectors. Start with no trading connection: configure the required account, instrument, balances, market/FX data, policy and active signing key. Submit a candidate order and verify the returned decision against its audit record. Test both an accepted and a policy-rejected order. Treat dry-run separately: no order-state changes and no order-decision audit record. Keep monetary values as decimal strings and handle the documented error shapes. Only add sending when I request that workflow and confirm the intended provider, account and paper/live mode. Keep evaluation, execution and execution reports distinct. Explain which enforcement and deployment boundaries my app must own. Show the files changed, commands used, observed results and remaining gaps. ``` For engine internals and SDK examples, continue at the [OpenPit wiki](https://wiki.openpit.dev/Getting-Started/). For custom Officer composition, use the [development notes](https://raw.githubusercontent.com/openpitkit/officer/main/docs/development.md).