> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get FIM One running in minutes — or try the cloud version instantly.

<Tip>
  **☁️ Option 0: Cloud (Zero Setup)**
  Don't want to self-host? Try FIM One instantly at [**cloud.fim.ai**](https://cloud.fim.ai/) — no Docker, no API keys, no configuration. Sign in and you're ready to go. *Early access.*
</Tip>

## Option A: Docker (Recommended)

No local Python or Node.js required — everything is built inside the container.

```bash theme={null}
git clone https://github.com/fim-ai/fim-one.git
cd fim-one

# Configure — only LLM_API_KEY is required
cp example.env .env
# Edit .env: set LLM_API_KEY (and optionally LLM_BASE_URL, LLM_MODEL)

# Build and run (first time, or after pulling new code)
docker compose up --build -d
```

Open [http://localhost:3000](http://localhost:3000) — on first launch you'll be guided through creating an admin account. That's it.

After the initial build, subsequent starts only need:

```bash theme={null}
docker compose up -d          # start (skip rebuild if image unchanged)
docker compose down           # stop
docker compose logs -f        # view logs
```

Data is persisted in Docker named volumes (`fim-data`, `fim-uploads`) and survives container restarts.

**Note:** Docker mode does not support hot reload. Code changes require rebuilding the image (`docker compose up --build -d`). For active development with live reload, use **Option B** below.

## Option B: Local Development

Prerequisites: Python 3.11+, [uv](https://docs.astral.sh/uv/), Node.js 18+, pnpm.

```bash theme={null}
git clone https://github.com/fim-ai/fim-one.git
cd fim-one

cp example.env .env
# Edit .env: set LLM_API_KEY

# Install
uv sync --all-extras
cd frontend && pnpm install && cd ..

# Launch (with hot reload)
./start.sh
```

| Command              | What starts                                             | URL                                                               |
| -------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
| `./start.sh`         | Next.js + FastAPI                                       | [http://localhost:3000](http://localhost:3000) (UI) + :8000 (API) |
| `./start.sh dev`     | Same, with hot reload (Python `--reload` + Next.js HMR) | Same                                                              |
| `./start.sh dev:api` | API only, dev mode (`--reload`)                         | [http://localhost:8000/api](http://localhost:8000/api)            |
| `./start.sh dev:ui`  | Next.js only, dev mode (HMR)                            | [http://localhost:3000](http://localhost:3000)                    |
| `./start.sh api`     | FastAPI only (headless, for integration or testing)     | [http://localhost:8000/api](http://localhost:8000/api)            |

## Configuration

FIM One works with **any OpenAI-compatible LLM provider** — OpenAI, DeepSeek, Anthropic, Qwen, Ollama, vLLM, and more.

| Provider           | `LLM_API_KEY` | `LLM_BASE_URL`                 | `LLM_MODEL`         |
| ------------------ | ------------- | ------------------------------ | ------------------- |
| **OpenAI**         | `sk-...`      | *(default)*                    | `gpt-4o`            |
| **DeepSeek**       | `sk-...`      | `https://api.deepseek.com/v1`  | `deepseek-chat`     |
| **Anthropic**      | `sk-ant-...`  | `https://api.anthropic.com/v1` | `claude-sonnet-4-6` |
| **Ollama** (local) | `ollama`      | `http://localhost:11434/v1`    | `qwen2.5:14b`       |

**[Jina AI](https://jina.ai/)** unlocks web search/fetch, embedding, and the full RAG pipeline (free tier available).

Minimal `.env`:

```bash theme={null}
LLM_API_KEY=sk-your-key
# LLM_BASE_URL=https://api.openai.com/v1   # default — change for other providers
# LLM_MODEL=gpt-4o                         # default — change for other models

JINA_API_KEY=jina_...                       # unlocks web tools + RAG
```

For a complete list of all configuration options, see the [Environment Variables](/configuration/environment-variables) reference.

## Production Deployment

### Docker (Recommended)

`docker compose up -d` brings up everything you need — **no manual service configuration required**:

| Service     | Purpose                      | Configured by                |
| ----------- | ---------------------------- | ---------------------------- |
| **fim-one** | API + Frontend               | `.env` (your LLM keys, etc.) |
| **Redis**   | Cross-worker interrupt relay | Auto-configured by compose   |

```bash theme={null}
docker compose up --build -d   # first time / after code changes
docker compose up -d           # subsequent starts
docker compose logs -f         # view logs
docker compose down            # stop all services
```

#### Scaling with Workers

By default, the API runs with a single worker process. To handle more concurrent users, increase workers via `.env`:

```bash theme={null}
WORKERS=4   # number of Uvicorn worker processes
```

Multi-worker requirements:

* **PostgreSQL** — SQLite is single-writer and does not support concurrent writes. Set `DATABASE_URL` to a PostgreSQL connection string.
* **Redis** — already included in Docker Compose (auto-configured). Handles cross-worker interrupt/inject relay.

With `WORKERS=1` (default), no Redis or PostgreSQL is needed — SQLite works fine.

#### Nginx Reverse Proxy

For HTTPS and custom domain, put an Nginx reverse proxy in front:

```
User → Nginx (443/HTTPS) → localhost:3000
```

The API runs internally on port 8000 — Next.js proxies `/api/*` requests automatically. Only port 3000 needs to be exposed.

#### Code Execution Sandbox

If you use the code execution sandbox (`CODE_EXEC_BACKEND=docker`), mount the Docker socket:

```yaml theme={null}
# docker-compose.yml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
```

#### Cloudflare Tunnel

For a zero-open-ports setup, use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) instead of Nginx. All traffic flows through Cloudflare's edge — no need to expose ports 80/443, manage SSL certificates, or configure firewall rules.

<Warning>
  **Mainland China users**: Cloudflare Free/Pro/Business plans have **no PoPs (Points-of-Presence) in mainland China**. Traffic from mainland China is routed to overseas edges (typically US West), causing frequent 502 errors and high latency. Do **not** use Cloudflare Tunnel if your primary users are in mainland China. Cloudflare Enterprise with China Network (JD Cloud partnership) is required for reliable mainland access.
</Warning>

```
User → Cloudflare Edge (SSL) → Tunnel → cloudflared → fim-one:3000
```

**Setup:**

<Steps>
  <Step title="Create a tunnel">
    Go to [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) → Networks → Tunnels → **Create a tunnel**.
    Choose **Cloudflared** as the connector type.
  </Step>

  <Step title="Configure the public hostname">
    In the tunnel config, add a public hostname:

    | Field    | Value          |
    | -------- | -------------- |
    | **Type** | `HTTP`         |
    | **URL**  | `fim-one:3000` |

    Leave all other settings (HTTP Host Header, Chunked Encoding, Timeouts, Access) at their defaults.

    <Note>The URL uses the Docker service name `fim-one`, not `localhost`, because `cloudflared` runs as a separate container in the same Docker network.</Note>
  </Step>

  <Step title="Copy the tunnel token">
    In the tunnel's **Configure** page, find the install command — it contains a token starting with `eyJ...`. Copy it.
  </Step>

  <Step title="Add the token to .env">
    ```bash theme={null}
    # Add to your .env file on the server
    CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiNj...
    ```
  </Step>

  <Step title="Deploy with the tunnel overlay">
    ```bash theme={null}
    docker compose -f docker-compose.yml -f docker-compose.tunnel.yml build
    docker compose -f docker-compose.yml -f docker-compose.tunnel.yml up -d
    ```

    The `docker-compose.tunnel.yml` overlay adds a `cloudflared` sidecar container. The base `docker-compose.yml` is unchanged — community users without Cloudflare can continue using `docker compose up -d` as before.
  </Step>

  <Step title="Remove the old DNS record">
    If your domain previously had an A record pointing to your server's IP, **delete it** in Cloudflare DNS. The tunnel automatically creates a CNAME record pointing to its edge endpoint.
  </Step>

  <Step title="Close server ports">
    Remove (or comment out) the `ports` section from `docker-compose.yml` on your server. Traffic now flows exclusively through the tunnel — no inbound ports needed.
  </Step>
</Steps>

<Tip>
  Cloudflare Tunnel is free on all plans including Free. There are no bandwidth or traffic limits.
</Tip>

### Script Deployment (Bare Metal)

For bare-metal servers or custom process managers, use `./start.sh` directly:

```bash theme={null}
./start.sh           # production mode
./start.sh portal    # same as above (explicit)
./start.sh api       # API only (headless)
```

In this mode, Redis is **not** included automatically. The system runs in single-worker, in-process mode by default — suitable for low-traffic deployments.

To enable multi-worker with Redis locally:

```bash theme={null}
# Start a Redis instance (Docker or system package)
docker run -d --name redis -p 6379:6379 redis:7-alpine

# Add to .env
REDIS_URL=redis://localhost:6379/0
WORKERS=4
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/fim_one
```