II-Agent: a self-hosted agent framework you run with make dev-all

What II-Agent solves, and for whom

Most agent demos stop at a script that calls a model and prints text. II-Agent starts from the other end: it is an application with a backend, a frontend, a database, object storage, a queue and a set of document and media tools. The README describes it as "an open-source AI agent built for real work", and the feature list is unusually broad for a single repository: mobile and website app development, storybook generation, video and image generation, fast and deep research, PDF and Excel and Word and PowerPoint handling, and prompt-to-deck slides.

That breadth defines the audience. According to the README, the target is "a solo developer, a research team, or an enterprise building internal tooling". The distinguishing property is bring-your-own-keys: MODEL_CONFIGS or model_configs.yaml hold your provider credentials, so cost and model choice stay with you. If you want an agent runtime you can fork and host, that is the pitch. If you want a function you import into an existing service, this is the wrong shape.

The architecture visible in the repository layout

The top-level entries tell you what starts when the stack comes up. src/ holds the Python backend, frontend/ the web client, migrations/ and alembic.ini the schema history, docker/ the Compose files, and scripts/ the supporting tooling. The Makefile names three Compose files: docker/docker-compose.dev.yaml for infrastructure only, and docker/docker-compose.stack.yaml for the full stack.

The runtime dependencies in pyproject.toml fill in the rest. FastAPI and uvicorn serve the API, SQLAlchemy with asyncpg talks to PostgreSQL, redis and celery handle background work, python-socketio carries live updates to the frontend, and e2b-code-interpreter plus libtmux and pexpect suggest code execution is expected to happen in a sandbox or a terminal session. Document handling is a long list of libraries: pymupdf, pdfminer-six, python-pptx, mammoth, pandas, weasyprint. Model access is multi-provider by design, with the anthropic, openai, google-genai and google-cloud-aiplatform clients all present.

One detail worth flagging: pyproject.toml declares version 0.1.0 while the release list goes to v0.4. The package metadata and the tag stream are not kept in step, which matters if you plan to pin by version number rather than by commit.

Installing II-Agent and starting the dev stack

The README lists three prerequisites: Docker, uv (installed with the curl command below), and Node.js with npm. The Makefile confirms the split, running uv sync --frozen for the backend and npm install inside frontend/.

curl -LsSf https://astral.sh/uv/install.sh | sh

After cloning the repository, make setup creates the .env files from their examples and installs both dependency sets. The Makefile's setup target depends on _ensure-env, _ensure-frontend-env and install, and prints a reminder to add LLM keys before continuing.

git clone https://github.com/Intelligent-Internet/ii-agent.git
cd ii-agent
make setup

At least one provider has to be configured. Option A puts a JSON array in .env; the .env.example shows the shape and lists OpenAI, Anthropic, Google, Cerebras and Custom as provider values.

MODEL_CONFIGS='[{"model_id":"gpt-5.2","provider":"OpenAI","api_key":"sk-...","display_name":"GPT-5.2","is_default":true}]'

Option B copies model_configs.example.yaml to model_configs.yaml, fills in the keys, and sets MODEL_CONFIGS_FILE=model_configs.yaml in .env. The README notes the example file also covers Vertex AI, Azure and self-hosted models.

make dev-all

According to the README, make dev-all starts the backend at http://localhost:8000, the frontend at http://localhost:1420, PostgreSQL on 5432, Redis on 6379 and MinIO at http://localhost:9001 with the credentials minioadmin/minioadmin. The frontend port is worth noting: the README's Quick Start says 1420 while .env.example sets II_FRONTEND_URL to http://localhost:5173, and the Makefile's frontend-dev target says port 5173. If the UI does not answer on the port you expect, check which target you ran before assuming a failure.

Running the full stack in Docker, and what it costs you

For a machine without Python or Node, the README offers a second path through docker/.stack.env. You copy the example, edit credentials, and use the stack targets.

cp docker/.stack.env.example docker/.stack.env
make stack

The Makefile supports make stack-build to rebuild images, make stack-down to stop and clean up, and make stack-logs to tail output. This is the more reproducible route, but it is also the heavier one: you are running a Compose project named ii-agent-stack with its own env file, separate from the dev project named ii-agent-dev.

The real cost of II-Agent is not the install command. It is the surface area. PostgreSQL, Redis and MinIO are all required for the documented paths, and .env.example shows the storage layer pointing at MinIO with STORAGE_PROVIDER=minio. There is a local storage option mentioned in that file's comment, but the default development configuration expects the S3-compatible service to be up. If your environment cannot run three stateful services next to the agent, the install will succeed and the application will not work.

Where II-Agent is the wrong tool

The README does not document rollback. It documents make db-migrate for running migrations forward, and the repository carries alembic.ini and a migrations/ directory, so schema changes are versioned, but nothing in the README describes downgrading a database or reverting a release. Plan accordingly: take a database dump before a migration, because the documented tooling moves in one direction.

A second boundary is the model configuration itself. Provider support is real, but model_id values are strings you supply, and the README's own examples (claude-sonnet-4-6, gpt-5.4 and gemini-3.1-pro-preview in the provider table; gpt-5.2 in .env.example; claude-opus-4-6 elsewhere) are inconsistent across the document. Treat the table as a shape, not a catalogue, and confirm the exact identifier with your provider before assuming a typo is a bug.

The third case is scope. If you need one agent loop inside an existing FastAPI service, pulling in Celery, Redis, MinIO, Socket.IO and a React frontend is not a trade you should make. The framework is opinionated toward being the whole product.

How it differs from a plain agent library

The obvious alternative is a minimal agent library you install with pip and call from your own code: you keep your database, your auth and your deployment, and the library supplies the reasoning loop and tool dispatch. II-Agent makes the opposite bet. It ships the auth (JWT via PyJWT, bcrypt, fastapi-sso, optional Google OAuth through GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET), the storage layer, the queue and the UI, and it also lists first-class MCP support through fastmcp and an A2A dependency (a2a-sdk) in pyproject.toml.

That difference decides the migration story. With a library, upgrading means bumping a version and reading a changelog. With II-Agent, upgrading means running migrations against your database and restarting a Compose stack, and the release cadence is visible in the tags: v0.2 in June 2025, v0.3 in July, v0.4 at the end of July. The last push to the repository was on 2026-08-16, so the project is not archived, but the tag stream and the push dates do not move together, and you should read the commit history rather than the release list if you need to know what changed recently.

Licence and the upgrade bill

Apache-2.0 covers the repository, which permits commercial use, modification and redistribution provided you keep the licence and notice files. The README leans on this directly, describing the project as "100% open source under the Apache-2.0 license" with "no vendor lock-in". That claim is about the code, not the models: your LLM spend runs through whichever provider keys you put in MODEL_CONFIGS, and nothing in the repository changes those terms. This is a description of the licence text, not legal advice.

The upgrade cost is mostly operational. Each release can carry migrations, so the sequence is make db-migrate against the new schema, then restart. Because rollback is undocumented, the practical safeguard is a snapshot before you migrate, plus a pinned commit rather than a floating main branch. The dependency list is long and tightly pinned in places (pydantic==2.11.7, fastmcp==2.10.6, playwright==1.55.0, uvicorn constrained below 0.30.0), which reduces surprise but also means a single conflicting pin can block an upgrade until you resolve it.

Editorial conclusion

Adopt II-Agent if you want a self-hosted agent application with a UI, multi-provider LLM configuration and Docker infrastructure you control, and if you are willing to run Postgres, Redis and MinIO alongside it. Do not adopt it if you need a small embeddable library, a pip-installable SDK, or a single dependency with no database. Before committing, verify that your chosen provider and model_id actually appear in model_configs.example.yaml, and confirm whether the migration path in migrations/ covers the schema version you deploy, because the README documents make db-migrate but not rollback.

Frequently asked questions

Official sources

1. Intelligent-Internet/ii-agent on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases