Skip to content
Browse the docs

ArchSim documentation

View on GitHubReport a problem with this page

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