ArchSim documentation
Everything about using, running, trusting and changing ArchSim. New here? Start with Getting started. The docs are published with the website, at archsim.io/docs.
Start here#
| Page | What it covers |
|---|---|
| Getting started | Run it in Docker or from source, a five-minute tour, the CLI and the MCP server |
| Features | Every workspace, technology behaviour and integration, with screenshots, and the scope and limitations |
| Troubleshooting | What to do when something doesn't start or runs stay queued |
Using ArchSim#
| Page | What it covers |
|---|---|
| Simulation model | What is and isn't modeled, and how each component behaves |
| Assumptions | Every default the engine uses, documented or illustrative (generated from the code) |
| Calibration | Setting a design's inputs from Prometheus metrics or OpenTelemetry traces |
| Importing a design | Starting from docker-compose, Kubernetes manifests or a Terraform plan |
| Prices and machine shapes | Real instance types and price snapshots behind every cost line |
| An SLO gate in CI | archsim check and the GitHub Action that comments on pull requests |
| AI agents | The MCP server for coding agents and the WebMCP tools in the browser |
| Performance | How fast the engine answers, and the sampled mode for long runs |
How accurate is it?#
| Page | What it covers |
|---|---|
| How accurate is ArchSim? | Predictions saved before measuring, then checked with k6 against real stacks |
| Java parity | The Java simulator against the frozen Python engine it replaced |
Running a server#
| Page | What it covers |
|---|---|
| Running ArchSim for a team | Several API instances and workers, sign-in, teams, API tokens, and what to do before exposing a server |
| Security policy and threat model | How to report a vulnerability, and how each threat is handled |
| HTTP API | Every endpoint under /api/v1 (OpenAPI at /api/v1/openapi.json, interactive docs at /api/v1/docs) |
| The API's module | Running the API and workers, their settings and the worker's heap |
Reference#
| Page | What it covers |
|---|---|
| Document schema | The design document, field by field, and how versions upgrade |
| Architecture | The layers, modules and how a run flows through them |
| Architecture decision records | Why ArchSim is built the way it is, decision by decision |
| The command line | Every archsim command, flag and exit code |
| The MCP server's module | What it serves and how it is tested |
Contributing#
| Page | What it covers |
|---|---|
| Contributing guide | Setup, checks, pull requests, and working with AI assistants |
| Contributor License Agreement | What a contributor licenses, AI-assisted work included (a draft under legal review) |
| Developing ArchSim | The repository layout and what the tests check |
| Java conventions | How the Java code is written, and what the build enforces |
| Adding a component type | A new technology, from the model to the engine |
| The website | How archsim.io is built from this repository, and how to preview it |
| Roadmap | Directions the design leaves room for |
Records#
How ArchSim got here, kept for reference:
| Page | What it covers |
|---|---|
| Changelog | What changed in each release |
| Implementation status | What is done, week by week |
| Implementation plan | The plan the first version was built against |
| The Java 25 port | The plan that moved the engine, API, CLI and MCP server from Python to Java |
| Template review | The audit of the built-in templates |
| UI critique and design principles | The review behind the current interface |