Kosmos runs a multi agent research loop, and the sandbox is the part you cannot turn off

Six agents, one orchestrator, and a loop that keeps going

Kosmos is an open source implementation of an autonomous AI scientist, built from the architecture described in the paper by Lu et al., and it is designed to be driven by Claude Code or an API.

The capability list in the documentation is the honest summary. It generates hypotheses from literature and data analysis, designs experiments to test them, executes code in sandboxed Docker containers, validates discoveries using an eight dimension quality framework, and builds knowledge graphs to track relationships between concepts. The system runs autonomous research cycles, generating tasks, executing analyses and synthesising findings into validated discoveries.

The agent architecture is a table of six roles. The Research Director is the master orchestrator coordinating all agents. The Hypothesis Generator produces testable hypotheses from literature. The Experiment Designer creates experimental protocols. The Data Analyst analyses results and interprets findings. The Literature Analyzer searches and synthesises papers. And the Plan Creator and Reviewer handle strategic task generation with a 70/30 exploration to exploitation ratio, which is the knob that decides how often the loop tries something new versus deepening what already worked.

The loop is a multi cycle process, and the Python API shows the shape of a run: you construct a ResearchWorkflow with a research objective and an artifacts directory, then ask it to run a number of cycles with a number of tasks per cycle, and finally ask it for a report.

The project badges are worth reading closely. The version badge says 0.2.0 alpha, the status badge says alpha, and the other two claim 17 of 17 paper implementation gaps complete and 3704 tests passing. So the coverage against the paper is claimed as complete, while the software itself is labelled alpha.

The Docker sandbox is the load-bearing part, and the fallback is not equivalent

The code execution section is where the project is most explicit about risk, and any evaluation should start there.

AI generated code runs in isolated Docker containers, and the documentation lists the isolation layers in a table. Container isolation uses --cap-drop=ALL with no privileged access. The network is disabled with --network=none. The filesystem is a read-only root with tmpfs for scratch. Resources are capped at 2 CPU cores, 2GB of memory and a 300 second timeout. And containers are pooled, with pre-warmed containers to reduce cold start.

The last point is not a security feature but it is an operational one: a research loop that starts a fresh container per code execution would spend most of its time waiting, so pooling is what makes the loop usable.

The fallback is the part to be careful about. Without Docker, the system falls back to CodeValidator static analysis plus exec(). The documentation says plainly that this is not recommended for untrusted inputs, and the earlier requirements section says the same thing in a different place.

That is a meaningful asymmetry rather than a caveat about performance. With Docker, model written code runs in a container with no network and no capabilities. Without Docker, it runs in your process. The static validator is a filter on syntax and obvious patterns, not a sandbox.

So the practical rule for a reader is that Docker is not an optional convenience here. If you cannot run Docker, you should not be letting this system execute code it generated.

Literature gets compressed in tiers, 20 to 1

An autonomous loop that reads papers will drown in context, and the compression strategy is the most interesting engineering in the project.

The system processes literature in batches rather than in bulk, and the method has four steps. First, relevance sorting: papers are ranked by query relevance before anything is processed. Second, batch size: the top 10 papers per batch. Third, statistics extraction, done with regex based extraction of p-values, sample sizes and effect sizes. Fourth, tiered summarisation, which is where the structure lives.

The tiers are explicit. At the task level, 42K lines of code become a 2 line summary plus the extracted statistics. At the cycle level, 10 task summaries become a cycle overview. At the synthesis level, 20 cycles become a final narrative. And the detail is lazy-loaded when it is needed again, so the full content is still reachable without being carried in every prompt.

The claimed effective ratio is about 20 to 1, and the implementation is in kosmos/compression/compressor.py.

The regex based statistics extraction is the part with a sharp edge. Pulling p-values and sample sizes out of paper text with regular expressions will work on a substantial fraction of papers and fail quietly on the rest, and a silently missing effect size is the kind of gap that propagates into a hypothesis. The architecture compensates by keeping the full content lazy-loadable, so the trade is deliberate rather than accidental, but it does mean the summary layer is lossy in a way you should verify against the source papers for any conclusion you actually care about.

Budget and concurrency are configuration you set, not policy you inherit

Two controls stand between the loop and an unbounded API bill, and both are set through environment variables.

Budget enforcement is enabled with BUDGET_ENABLED and the ceiling is BUDGET_LIMIT_USD. When the limit is reached, budget enforcement raises BudgetExceededError and the documentation says the research transitions gracefully to completion, which is a better failure mode than a hard stop mid experiment.

Concurrency is capped by three independent limits defined in kosmos/config.py, and the documentation gives the defaults and the ranges:

| `max_parallel_hypotheses` | 3 | 1-10 |
| `max_concurrent_experiments` | 10 | 1-16 |
| `max_concurrent_llm_calls` | 5 | 1-20 |

The note under that table is telling. The paper describes 10 parallel tasks, and the documentation says the default now matches the paper specification. That tells you the numbers are not arbitrary tuning, they are an attempt to match the behaviour described in the original work, which is exactly what you want from an implementation project and exactly what you would want to change if your own budget or hardware could not support it.

The model provider is chosen the same way. LLM_PROVIDER selects anthropic, openai or litellm, with the LiteLLM path documented as supporting 100 or more providers including local models, and the example pointing at an Ollama model on a local port. That last option is the one to know about if you care about where the data goes, because a local model keeps the literature and the generated code inside your own machine.

The environment file in the repository is where all of this lives, and it also documents an option to route through the Claude Code CLI by setting the API key to a placeholder value, which the file explains is for Max subscription users and requires the CLI to be installed and authenticated.

Installing is a clone, an editable install and a key

The requirements are Python 3.11 or newer, an Anthropic API key or an OpenAI API key, and Docker, which is recommended for code execution. The installation is four commands:

git clone https://github.com/jimmc414/Kosmos.git
cd Kosmos
pip install -e .
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY or OPENAI_API_KEY

The editable install means the package is importable from the checkout, and the .env file is where the provider and the key are configured.

Verification is two steps, and the documentation is right to insist on them:

python scripts/smoke_test.py

# Run unit tests
pytest tests/unit/ -v --tb=short

The smoke test exercises the installation end to end, and the unit suite runs the tests under tests/unit. Running both before you spend anything on a research cycle is the sensible order, because a broken dependency or a missing key will otherwise show up as a failed run in the middle of a multi cycle loop.

The package metadata fills in the rest. The distribution is named kosmos-ai-scientist, the version is 0.2.0, it requires Python 3.11 or newer, the licence is declared as MIT, and the classifiers mark it as Development Status 3 - Alpha, intended for science and research audiences, and as a scientific and engineering artificial intelligence project.

The dependency set is a good summary of what the system does. The Anthropic and OpenAI clients are there for the providers, pydantic and pydantic-settings for configuration and validation, SQLAlchemy with alembic and redis for state and caching, httpx with tenacity for HTTP and retry, and the scientific stack of numpy, pandas, scipy, scikit-learn and statsmodels, where numpy is pinned to 1.x and scipy to below 1.14.0 for compatibility.

The CLI exposes the same loop with different levels of noise

The command line entry points are the same research workflow with a range of output settings, and reading the flags tells you what the author expected people to run first.

kosmos run "What metabolic pathways differ between cancer and normal cells?" --domain biology

# With budget limit
kosmos run "How do perovskites optimize efficiency?" --domain materials --budget 50

# Interactive mode (recommended for first time)
kosmos run --interactive

# Maximum verbosity
kosmos run "Your question" --domain biology --trace

# Real-time streaming display
kosmos run "Your question" --stream

# Streaming with token display disabled
kosmos run "Your question" --stream --no-stream-tokens

# Show system information
kosmos info

# Run diagnostics
kosmos doctor

The interactive mode is marked as recommended for the first time, which is a sensible default for a tool that will make API calls and write files. The budget flag caps spending per run, the domain flag records which scientific domain the run belongs to, and the trace flag turns on maximum verbosity.

Two flags are about the output stream rather than the run. --stream gives real time streaming display, and --stream --no-stream-tokens keeps the streaming but suppresses the token display, which is the combination you want when the events matter but the token-by-token output is noise.

The remaining two commands are for diagnosis rather than research. kosmos info shows system information and kosmos doctor runs diagnostics, and having a doctor command in an alpha tool is a small sign that the author expected people to hit configuration problems.

The Python API and the CLI are the same system underneath, so the choice between them is about ergonomics rather than capability. The programmatic route gives you the result object and the report, the CLI gives you the same thing with streaming and tracing. The features table lists real time streaming as SSE and WebSocket events, which is how the web interface at port 8000 in the compose file is wired.

Alpha, a licence split, and a lot of repository around the code

The maintenance picture is healthy in the sense that matters most for a research project: it is being worked on. The repository is not archived and the last push was on 2026-10-09. There are no GitHub releases, so the alpha version in the package metadata, 0.2.0, is the version to track rather than a tag.

The licence needs one clarifying sentence. The package metadata declares MIT, with the OSI approved MIT classifier, while the licence field of the repository itself is left unclassified, which is what GitHub reports when a project uses a licence it cannot categorise. Read the LICENSE file before you vendor it.

The repository layout is worth a look, because it shows the scope of the effort. There is the kosmos/ package itself, the evaluation/ directory for the quality framework, paper/ for the reference material, prompts/ for the prompt templates, tests/ with both unit and integration suites, scripts/, an archive/ and an archived/ directory holding earlier work, a human_review_audit.jsonl file at the root, an alembic/ directory with alembic.ini for database migrations, a Dockerfile and docker-compose.yml, a k8s/ directory, and separate directories for documentation and onboarding. There is also a .claude/ directory and a kosmos-claude-scientific-skills/ directory, which lines up with the project description saying it is meant to be driven by Claude Code.

The examples directory is uneven. It has real scripts for biology, for example 01_biology_metabolic_pathways.py and 02_biology_gene_expression.py, followed by numbered placeholder files, which suggests a series that was planned and not finished.

One oddity in the Dockerfile: the version label says 0.10.0 while the package version is 0.2.0. It is a cosmetic inconsistency in an image label, but it is the kind of thing to check when you are pinning images in a deployment.

Editorial conclusion

Use Kosmos if you are prototyping an autonomous discovery pipeline and you have Docker, Python 3.11 and a model API key, and you want to see the whole loop, the compression and the budget controls in one place. Do not deploy it on untrusted input without Docker, because the documented fallback is static validation plus exec(), and do not treat its output as a discovery, because the project is alpha and its own quality framework is a filter rather than a proof. Before running it, read the sandbox section, set BUDGET_ENABLED and BUDGET_LIMIT_USD, and run the smoke test and pytest suite to confirm the installation before you point it at an expensive model.

Frequently asked questions

Official sources

1. Issues
2. jimmc414/Kosmos on GitHub
3. README