Setup Guide

This is the current setup path for this repo. It is intentionally modeled on the OpenClaw docs style: start with the fastest working path, then move outward to full-stack setup, cloud credentials, external tool services, and docs deployment.

note

Several names from the older docs are stale. The current setup uses:

MODEL_CONFIGS or MODEL_CONFIGS_FILE, not LLM_CONFIGS
STORAGE_*, not SLIDE_ASSETS_* / FILE_UPLOAD_* / AVATAR_*
TOOL__... for in-process tool settings in .env
unprefixed ..._CONFIG__... keys for the standalone ii_agent_tools service

What you need

Docker Desktop or Docker Engine with Compose v2
uv
Node.js 20+ and npm
Python 3.10+
At least one model configuration through MODEL_CONFIGS or MODEL_CONFIGS_FILE
A Google Cloud service-account JSON only if you need GCS, Vertex AI, or Secret Manager

tip

Check the local toolchain first:

docker --version
uv --version
node --version
npm --version
python3 --version

Quick start

Bootstrap the repo:
```
make setup
```
This copies .env.example to .env and frontend/.env.example to frontend/.env if they do not exist, then installs backend and frontend dependencies.
Add at least one model:
- Use MODEL_CONFIGS='[...]' directly in .env, or
- Copy model_configs.example.yaml to model_configs.yaml and keep MODEL_CONFIGS_FILE=model_configs.yaml
Start the recommended local development path:
```
make dev-all
```
This starts Postgres, Redis, and MinIO in Docker, then runs the backend and frontend locally.
Verify the app:
```
curl http://localhost:8000/health
```
Then open http://localhost:1420.
Use the Docker stack only when you need service parity:
```
make stack-build
```

Choose the right mode

Mode	Command	Use it when	Env file
Local development	`make dev-all`	Fastest iteration on backend + frontend	`.env`
Infra only	`make infra`	You want to run backend/frontend by hand	`.env`
Full stack	`make stack-build`	You want the backend, sandbox server, tool server, and worker in Docker	`docker/.stack.env`
Docs only	`make docs-dev`	You are editing the Docusaurus site	`docs/docusaurus/*`

Local installation

make setup is the primary entrypoint for a developer machine.

Required `.env` keys

Key	Why it matters
`DATABASE_URL`	Backend database connection. The default matches `make infra`.
`REDIS_SESSION_URL`	Redis for session/pubsub state.
`STORAGE_PROVIDER`, `STORAGE_BUCKET_NAME`	Local development defaults to MinIO.
`JWT_SECRET_KEY`	Signs backend JWTs.
`SESSION_SECRET_KEY`	Encrypts session cookies for OAuth.
`II_FRONTEND_URL`	Backend-generated links and OAuth redirects.
`MODEL_CONFIGS` or `MODEL_CONFIGS_FILE`	At least one model must exist or the app has nothing to run.

Recommended local flow

Run make setup.
Edit .env.
If you want YAML-based model config, copy the example:
```
cp model_configs.example.yaml model_configs.yaml
```
Start the app:
```
make dev-all
```
Validate the services:
- Backend: http://localhost:8000/health
- Frontend: http://localhost:1420
- MinIO console: http://localhost:9001

note

The old docs assumed II_FRONTEND_URL=http://localhost:5173. The current Vite dev server runs on port 1420, and .env.example now reflects that.

Full Docker stack

Use this when you want the closest local match to the containerized deployment.

Step 1: create `docker/.stack.env`

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

make stack-build will also create it automatically if it is missing.

Step 2: fill the current required values

At minimum, set these keys in docker/.stack.env:

JWT_SECRET_KEY
SESSION_SECRET_KEY
AUTH_SECRET_KEY
MODEL_CONFIGS or equivalent model config
GOOGLE_APPLICATION_CREDENTIALS if the stack writes to GCS or uses Vertex AI
STORAGE_PROVIDER, STORAGE_PROJECT_ID, STORAGE_BUCKET_NAME if you use GCS

Step 3: boot the stack

make stack-build

This uses scripts/run_stack.sh, which now starts:

postgres
redis
tool-server
sandbox-server
backend
celery
frontend

Step 4: verify the services

curl http://localhost:8000/health
curl http://localhost:1236/health
curl http://localhost:8100/health

If you need logs:

make stack-logs

To stop everything:

make stack-down

GCP setup

You only need Google Cloud credentials when you use one or more of these:

STORAGE_PROVIDER=gcs
Vertex-hosted models
Google AI Studio / Gemini media generation
GCP Secret Manager

Step 1: create a service account

Create one service account for local development or staging. The minimal role set depends on what you use:

Cloud Storage access for STORAGE_*
Vertex AI access for GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION
Secret Manager access for GCP_PROJECT_ID / GCP_SECRET_PREFIX

Step 2: download the JSON key

Store it outside the repo, then point the env var at the absolute path:

GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json

Step 3: switch storage from MinIO to GCS

For local .env:

STORAGE_PROVIDER=gcs
STORAGE_PROJECT_ID=your-gcp-project-id
STORAGE_BUCKET_NAME=your-gcs-bucket
STORAGE_CUSTOM_DOMAIN=

For Vertex-backed models or media generation, also set:

GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=global

tip

Keep MinIO for the fast local loop. Only switch to GCS when you are explicitly testing cloud storage or Vertex-specific behavior.

`ii-agent-tools`: in-process vs external service

This repo currently vendors ii_agent_tools, and there are two valid ways to configure it.

Option A: in-process tool client

This is the default path for local development. The backend imports ii_agent_tools.client directly, so the env vars use the TOOL__ prefix.

Examples:

TOOL__WEB_SEARCH_CONFIG__SERPAPI_API_KEY=
TOOL__WEB_VISIT_CONFIG__FIRECRAWL_API_KEY=
TOOL__IMAGE_GENERATE_CONFIG__OPENAI_API_KEY=
TOOL__VOICE_GENERATE_CONFIG__ELEVENLABS_API_KEY=
TOOL__STORAGE_CONFIG__GCS_PROJECT_ID=
TOOL__STORAGE_CONFIG__GCS_BUCKET_NAME=
TOOL__LLM_CONFIG__OPENAI_API_KEY=

Use this when you run make dev-all.

Option B: standalone HTTP service

The Docker stack also starts a separate tool-server container that runs:

uvicorn ii_agent_tools.app.main:app --host 0.0.0.0 --port 1236

In that mode the env names lose the TOOL__ prefix because the service reads ii_agent_tools.app.Settings directly.

Examples:

AUTH_SECRET_KEY=change-me-32-chars-minimum
STORAGE_CONFIG__GCS_PROJECT_ID=
STORAGE_CONFIG__GCS_BUCKET_NAME=
WEB_SEARCH_CONFIG__SERPAPI_API_KEY=
WEB_VISIT_CONFIG__FIRECRAWL_API_KEY=
IMAGE_GENERATE_CONFIG__OPENAI_API_KEY=
VOICE_GENERATE_CONFIG__ELEVENLABS_API_KEY=

Which one should you use?

Use the in-process TOOL__... settings for normal local backend work.
Use the standalone service only when you intentionally want Dockerized service parity or a separate tool-service boundary.

Docs development

The docs source lives in docs/docusaurus.

Install the docs dependencies

make docs-install

Run the docs site locally

make docs-dev

Because the Docusaurus config uses the repo Pages base URL, the local dev URL is:

http://localhost:3000/

Build the static site

make docs-build

The production output lands in docs/docusaurus/build.

Publish on GitHub Pages

This repo is already laid out for GitHub Pages.

Step 1: keep the Docusaurus site configured for Pages

docs/docusaurus/docusaurus.config.ts should use:

url = https://intelligent-internet.github.io
baseUrl = /
organizationName = Intelligent-Internet
projectName = ii-agent-prod

Step 2: enable Pages in the repository settings

In GitHub:

Open Settings
Open Pages
Set Source to GitHub Actions

Step 3: use the docs deployment workflow

This repo now includes .github/workflows/docs-deploy.yml, which:

installs the Docusaurus dependencies
builds docs/docusaurus
uploads docs/docusaurus/build
deploys the artifact to GitHub Pages

Step 4: validate locally before pushing

make docs-build

Step 5: push to `main`

The GitHub Actions workflow deploys the site automatically on pushes to main when docs-related files change.

Step 6: verify the published URL

https://intelligent-internet.github.io/

Verification checklist

Use this after any setup change:

make dev-all works with the current .env
curl http://localhost:8000/health returns {"status":"ok"}
make stack-build brings up the containerized stack when docker/.stack.env is populated
make docs-build succeeds before you push docs changes

What you need​

Quick start​

Choose the right mode​

Local installation​

Required .env keys​

Recommended local flow​

Full Docker stack​

Step 1: create docker/.stack.env​

Step 2: fill the current required values​

Step 3: boot the stack​

Step 4: verify the services​

GCP setup​

Step 1: create a service account​

Step 2: download the JSON key​

Step 3: switch storage from MinIO to GCS​

ii-agent-tools: in-process vs external service​

Option A: in-process tool client​

Option B: standalone HTTP service​

Which one should you use?​

Docs development​

Install the docs dependencies​

Run the docs site locally​

Build the static site​

Publish on GitHub Pages​

Step 1: keep the Docusaurus site configured for Pages​

Step 2: enable Pages in the repository settings​

Step 3: use the docs deployment workflow​

Step 4: validate locally before pushing​

Step 5: push to main​

Step 6: verify the published URL​

Verification checklist​