FAROS: a blueprint-driven AutoResearch runtime for AI scientist workflows

What FAROS is for, and who it is aimed at

FAROS stands for Foundation AutoResearch Operating System. The README frames it as a collaborative AI Scientist system that runs from a research question to auditable evidence, and the repository topics confirm the scope: automated research, paper generation, multi-agent orchestration, AI for science. The audience is narrower than those tags suggest. The current release, per the README, focuses first on LLM and AI Scientist research, and the project describes itself as a release candidate for competition validation and research prototyping rather than a production system that replaces a researcher. So the realistic user is a lab or a small team already doing LLM research that wants the scaffolding around the work: literature evidence, a plan, generated code, recorded runs, a paper draft and a review report, all linked by identifiers. The README lists six recurring problems it tries to answer, among them that vague interests are hard to turn into search queries, that generated ideas often lack grounding, and that automatic review produces comments nobody can act on. Each of those maps to a component rather than to a model prompt.

PlanPackage is the contract, not the prompt

The mechanism that separates FAROS from a chain of model calls is PlanPackage. The README states it is the cross-module contract, and it carries the hypothesis, experiment variables, staged steps, acceptance conditions and evidence references as a structured object. Downstream code generation reads that object instead of guessing intent from prose, and ReviewX can trace a claim back through the same references. The pipeline runs Idea, PlanPackage, Code, Experiment, Paper, ReviewX, then a human review gate; a failed review sends the flow back to Idea rather than patching the paper in place. Two design choices stand out. First, a literature quality gate runs before idea generation, and the README draws a distinction between finding papers and finding papers that actually support the current question. Second, long tasks such as topic recommendation and plan generation run as background jobs with short polling, so a browser refresh recovers results instead of resubmitting and re-billing model calls. The runtime underneath is built from Blueprint, Capability, Profile and Provider components, which is what the project means by extensible: new research flows are meant to arrive as Blueprints rather than as edits to the core.

Installing FAROS and running a first topic recommendation

The README gives a two-process local setup. Requirements are Python 3.11+, Node.js 18+, and at least one compatible LLM provider, with Qwen recommended. Docker is optional for browsing and light development but the README states it is mandatory for the formal Code and Experiment sandbox. Clone the repository and install the backend dependencies in a virtual environment.

git clone https://github.com/OpenNSWM-Lab/FAROS.git
cd FAROS/backend
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Start the API with uvicorn on port 8005. The README uses this exact host and port, and the API documentation is served at /api/docs on the same port.

uvicorn app.main:app --host 127.0.0.1 --port 8005 --reload

In a second terminal, install and start the frontend, pointing it at the backend. The README says to open http://127.0.0.1:5176.

cd FAROS/frontend
npm ci
VITE_API_BASE_URL=http://127.0.0.1:8005 npm run dev

For the model provider, the README recommends configuring the API key per account under Settings / LLM Provider in the interface. The environment variable route is documented as an alternative, set before the backend starts.

export ACTIVE_PROVIDER_NAME=qwen
export QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export QWEN_API_KEY=your_api_key

After that, the first real use is the Idea stage: give the system a rough research interest, and the README states Qwen rewrites it into an executable topic that names the task, method, dataset and evaluation metrics. The README also ships a dependency checker you can run before any of this on Ubuntu, with a role argument for local installs.

./scripts/check_deployment_dependencies.sh --role local

If you intend to generate real paper PDFs rather than fallback output, the README requires latexmk, XeLaTeX, the ctex Chinese macro package and a CJK font on the machine.

Where FAROS will not save you: PDF toolchain, Docker and human gates

Three constraints in the README are worth taking literally. The PDF toolchain is the sharpest. Without latexmk, XeLaTeX, ctex and a CJK font, the system can only produce a fallback PDF, which means the Paper stage degrades quietly unless you check the output. The Code and Experiment stages have a similar hard dependency: Docker Engine is required for the formal sandbox, so a laptop without it can browse and develop but cannot run the experiment path as designed. The third constraint is architectural rather than environmental. FAROS keeps human decision points at plan approval, experiment interpretation and final review. That is deliberate, and it means the system is not built to run unattended end to end; a team hoping to point it at a question and collect a finished paper is using it against its own design. The README's own boundary section is explicit that cross-disciplinary experiment execution, additional domain Blueprints, large-scale parallel scheduling and broader human evaluation are still being built, and that important conclusions should keep human review and inspection of the original evidence. The verification section lists 644 backend tests and 35 frontend tests passing, alongside a TypeScript production build and a real Qwen topic-recommendation flow. Note that the README's own status badges and its verification section disagree on the numbers, showing 685 and 41 in the badges and 644 and 35 in the text, so treat the smaller figures as the stated baseline.

How FAROS differs from a generic agent framework

The obvious comparison is a general-purpose agent framework such as LangGraph or CrewAI, where you define nodes, edges and tool calls and the framework executes them. Those tools give you orchestration primitives and leave the research semantics to you. FAROS inverts that: the research semantics are the product, and the orchestration is largely fixed. PlanPackage, the evidence gate before ideation, the claim-evidence-experiment check in ReviewX and the human approval gates are all opinions about how research should proceed. If your workflow does not resemble a paper pipeline, that structure is overhead rather than help. A second comparison is a single-shot paper generator, which typically turns a prompt into a draft. FAROS instead keeps a traceable chain from literature through runs to claims, and the README's ReviewX description is the clearest statement of intent: it checks whether paper claims, cited evidence and experimental measurements agree, and lets real experiment results change the next research plan. That is a heavier loop, and it only pays off if you actually run experiments the system can measure. The trade-off is real in both directions: you get provenance and a structured handoff, and you give up the freedom to define an arbitrary graph.

Maintenance, licensing and upgrade questions

The repository is not archived, and the last push was on 2026-09-05, so the codebase is current. There are no releases retrieved for the project, yet the README badge and the deployment notes reference version 1.1.0-rc1, which tells you the project is distributing release candidates rather than tagged stable versions. Plan for that: an upgrade may move the PlanPackage schema or the module APIs, and the README does not document a migration path or a rollback procedure for either. The practical hedge is to pin the commit you deploy and read the Idea-to-Plan handoff guide and the developer guide under docs/ before pulling. On licensing, the repository metadata does not state a licence, and the README does not mention one either. That matters more here than in a typical library, because FAROS stores provider API keys encrypted per user and expects a credential key plus a trusted reverse proxy injecting a user header. The README warns against committing real API keys to Git and says production deployments should set FAROS_CREDENTIAL_KEY. Until a licence file appears, treat the terms of use as undefined and get clarity from the maintainers before deploying it anywhere shared.

Editorial conclusion

Adopt FAROS if you already run LLM or AI Scientist research and want provenance, a structured PlanPackage handoff and a review loop that ties claims to experiments; the README describes it as a release candidate for competition validation and research prototyping, so treat it as a supervised workbench. Skip it if you need an unsupervised system that replaces a researcher, since the documentation states cross-disciplinary experiment execution, more domain Blueprints, large-scale parallel scheduling and broader human evaluation are still being built. Before committing, verify three things: that Docker Engine is available for Code and Experiment sandboxes, that latexmk, XeLaTeX, the ctex package and a CJK font are installed if you need real PDF output, and that FAROS_CREDENTIAL_KEY is set behind a reverse proxy that injects X-Faros-User, because provider credentials are stored encrypted per user.

Frequently asked questions

Official sources

1. Issues
2. OpenNSWM-Lab/FAROS on GitHub
3. README