CERBERUS/ollama
1
0
Fork 0
mirror of https://github.com/ollama/ollama.git synced 2026-10-21 02:51:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

documentation re-structuring

Browse source
This commit is contained in:
Anna Rahn 2026-10-06 12:28:15 -07:00
parent 02dc3ea4c3
commit cba2a9cd52
13 changed files with 840 additions and 354 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/README.md
View file

@ -1,13 +1,19 @@
# Documentation
### Getting Started
### Getting started
* [Quickstart](https://docs.ollama.com/quickstart)
* [Ollama Cloud](https://docs.ollama.com/cloud)
* [Run Ollama locally](https://docs.ollama.com/local)
* [Examples](./examples.md)
### Local
* [macOS](https://docs.ollama.com/macos)
* [Linux](https://docs.ollama.com/linux)
* [Windows](https://docs.ollama.com/windows)
* [Docker](https://docs.ollama.com/docker)
* [Importing models](https://docs.ollama.com/import)
* [MacOS Documentation](https://docs.ollama.com/macos)
* [Linux Documentation](https://docs.ollama.com/linux)
* [Windows Documentation](https://docs.ollama.com/windows)
* [Docker Documentation](https://docs.ollama.com/docker)
### Reference
@ -19,5 +25,6 @@
### Resources
* [Troubleshooting Guide](https://docs.ollama.com/troubleshooting)
* [FAQ](https://docs.ollama.com/faq)
* [Local FAQ](https://docs.ollama.com/faq)
* [Cloud FAQ](https://docs.ollama.com/cloud/faq)
* [Development guide](./development.md)

23
docs/api/introduction.mdx
View file

@ -1,30 +1,43 @@
---
title: Introduction
description: Use the Ollama API locally or through Ollama Cloud with a shared request format.
---
Use Ollama's API to run and interact with models.
## Get started
Follow the [quickstart](/quickstart) to install Ollama and make your first request.
Choose how the request reaches the model:
## Base URL
| Access path | Model runs on | Base URL | Authentication and model name |
| --- | --- | --- | --- |
| [Local model](/local) | Your hardware | `http://localhost:11434/api` | None by default; use the local model name |
| [Cloud model through Ollama](/cloud/models) | Ollama Cloud | `http://localhost:11434/api` | Run `ollama signin`; use a model name ending in `:cloud` |
| [Direct Cloud API](/cloud/api) | Ollama Cloud | `https://ollama.com/api` | Send an Ollama API key; use the Cloud API model name |
After installation, Ollama's API is served by default at:
Request bodies have the same shape for shared endpoints. The host, authentication, and model name depend on the access path.
## Local API
After you [install Ollama](/local), its API is served by default at:
```
http://localhost:11434/api
```
For running cloud models on [ollama.com](https://ollama.com), the same API is available with the following base URL:
## Cloud API
For direct access to models hosted on Ollama Cloud, use:
```
https://ollama.com/api
```
Cloud API requests require an API key. See [Cloud API authentication](/cloud/api#authentication).
## Example request
Once Ollama is running, its API is automatically available and can be accessed via `curl`:
Once Ollama is running locally, its API is automatically available and can be accessed with `curl`:
```shell
curl http://localhost:11434/api/generate -d '{

293
docs/cloud.mdx
View file

@ -1,292 +1,39 @@
---
title: Cloud
sidebarTitle: Cloud
title: Ollama Cloud
sidebarTitle: Overview
description: Choose how to run Ollama Cloud models through the Ollama CLI, a local API, or the direct Cloud API.
---
## Cloud Models
Ollama Cloud runs larger models without requiring a powerful GPU. Cloud models support the same capabilities as local models, but inference runs on Ollama's cloud service.
Ollama's cloud models are a new kind of model in Ollama that can run without a powerful GPU. Instead, cloud models are automatically offloaded to Ollama's cloud service while offering the same capabilities as local models, making it possible to keep using your local tools while running larger models that wouldn't fit on a personal computer.
## Choose how to connect
### Supported models
<CardGroup cols={2}>
<Card title="Use Cloud models from Ollama" icon="terminal" href="/cloud/models">
Use the Ollama CLI, Python or JavaScript library, or your local Ollama API. Cloud model names use the `:cloud` suffix.
</Card>
For a list of supported models, see Ollama's [model library](https://ollama.com/search?c=cloud).
<Card title="Call the Cloud API directly" icon="cloud" href="/cloud/api">
Send authenticated requests to `https://ollama.com/api` without installing Ollama.
</Card>
</CardGroup>
### Running Cloud models
Both options require an Ollama account. Browse the available models in the [cloud model library](https://ollama.com/search?c=cloud).
Ollama's cloud models require an account on [ollama.com](https://ollama.com). To sign in or create an account, run:
## Cloud models
```
ollama signin
```
<Tabs>
<Tab title="CLI">
To run a cloud model, open the terminal and run:
```
ollama run gpt-oss:120b-cloud
```
</Tab>
<Tab title="Python">
First, pull a cloud model so it can be accessed:
```
ollama pull gpt-oss:120b-cloud
```
Next, install [Ollama's Python library](https://github.com/ollama/ollama-python):
```
pip install ollama
```
Next, create and run a simple Python script:
```python
from ollama import Client
client = Client()
messages = [
{
'role': 'user',
'content': 'Why is the sky blue?',
},
]
for part in client.chat('gpt-oss:120b-cloud', messages=messages, stream=True):
print(part['message']['content'], end='', flush=True)
```
</Tab>
<Tab title="JavaScript">
First, pull a cloud model so it can be accessed:
```
ollama pull gpt-oss:120b-cloud
```
Next, install [Ollama's JavaScript library](https://github.com/ollama/ollama-js):
```
npm i ollama
```
Then use the library to run a cloud model:
```typescript
import { Ollama } from "ollama";
const ollama = new Ollama();
const response = await ollama.chat({
model: "gpt-oss:120b-cloud",
messages: [{ role: "user", content: "Explain quantum computing" }],
stream: true,
});
for await (const part of response) {
process.stdout.write(part.message.content);
}
```
</Tab>
<Tab title="cURL">
First, pull a cloud model so it can be accessed:
```
ollama pull gpt-oss:120b-cloud
```
Run the following cURL command to run the command via Ollama's API:
```
curl http://localhost:11434/api/chat -d '{
"model": "gpt-oss:120b-cloud",
"messages": [{
"role": "user",
"content": "Why is the sky blue?"
}],
"stream": false
}'
```
</Tab>
</Tabs>
Follow [Use Cloud models from Ollama](/cloud/models) to run a `:cloud` model from the CLI, official libraries, or the local Ollama API.
## Cloud API access
Cloud models can also be accessed directly on ollama.com's API. In this mode, ollama.com acts as a remote Ollama host.
### Authentication
For direct access to ollama.com's API, first create an [API key](https://ollama.com/settings/keys).
Then, set the `OLLAMA_API_KEY` environment variable to your API key.
```
export OLLAMA_API_KEY=your_api_key
```
### Listing models
For models available directly via Ollama's API, models can be listed via:
```
curl https://ollama.com/api/tags
```
### Generating a response
<Tabs>
<Tab title="Python">
First, install [Ollama's Python library](https://github.com/ollama/ollama-python)
```
pip install ollama
```
Then make a request
```python
import os
from ollama import Client
client = Client(
host="https://ollama.com",
headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')}
)
messages = [
{
'role': 'user',
'content': 'Why is the sky blue?',
},
]
for part in client.chat('gpt-oss:120b', messages=messages, stream=True):
print(part['message']['content'], end='', flush=True)
```
</Tab>
<Tab title="JavaScript">
First, install [Ollama's JavaScript library](https://github.com/ollama/ollama-js):
```
npm i ollama
```
Next, make a request to the model:
```typescript
import { Ollama } from "ollama";
const ollama = new Ollama({
host: "https://ollama.com",
headers: {
Authorization: "Bearer " + process.env.OLLAMA_API_KEY,
},
});
const response = await ollama.chat({
model: "gpt-oss:120b",
messages: [{ role: "user", content: "Explain quantum computing" }],
stream: true,
});
for await (const part of response) {
process.stdout.write(part.message.content);
}
```
</Tab>
<Tab title="cURL">
Generate a response via Ollama's chat API:
```
curl https://ollama.com/api/chat \
-H "Authorization: Bearer $OLLAMA_API_KEY" \
-d '{
"model": "gpt-oss:120b",
"messages": [{
"role": "user",
"content": "Why is the sky blue?"
}],
"stream": false
}'
```
</Tab>
</Tabs>
Follow the [Cloud API guide](/cloud/api) to call `https://ollama.com/api` directly with an API key.
## Local only
Ollama can run in local-only mode by [disabling Ollama's cloud](./faq#how-do-i-disable-ollama-cloud-features) features.
Use [Local](/local) when you want inference to run on hardware you control. Ollama can also run in [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled.
## Retirements
Ollama will occasionally deprecate and retire older cloud models as newer and better open-source models are released.
Tools and applications relying on Ollama Cloud models may need to be updated to keep working. Impacted users will be
notified in advance of model deprecation and retirement. Deprecations will be communicated through email and on the
Ollama website.
Cloud models may be deprecated as newer models become available. See [Cloud model lifecycle](/cloud/model-lifecycle) for upcoming and past retirements.
Ollama Cloud model retirement does not affect local models.
### Upcoming retirements
| Retirement date | Model | Recommended alternative |
| --- | --- | --- |
| July 31, 2026 | `minimax-m2.5` | `minimax-m2.7` |
| July 31, 2026 | `kimi-k2.5` | `kimi-k2.6` |
### Past retirements
<AccordionGroup>
<Accordion title="July 15, 2026">
| Model | Recommended alternative |
| --- | --- |
| `deepseek-v3.1:671b` | `deepseek-v4-flash` |
| `deepseek-v3.2` | `deepseek-v4-flash` |
| `devstral-2:123b` | `mistral-large-3:675b` |
| `devstral-small-2:24b` | |
| `ministral-3:14b` | |
| `ministral-3:3b` | |
| `ministral-3:8b` | |
| `gemini-3-flash-preview` | `minimax-m3` |
| `gemma3:12b` | `gemma4:31b` |
| `gemma3:27b` | `gemma4:31b` |
| `gemma3:4b` | `gemma4:31b` |
| `glm-4.7` | `glm-5.2` |
| `glm-5` | `glm-5.2` |
| `minimax-m2.1` | `minimax-m3` |
| `qwen3-coder-next` | `qwen3.5:397b` |
| `qwen3-coder:480b` | `qwen3.5:397b` |
</Accordion>
<Accordion title="June 30, 2026">
| Model | Recommended alternative |
| --- | --- |
| `rnj-1:8b` | |
</Accordion>
<Accordion title="June 16, 2026">
| Model | Recommended alternative |
| --- | --- |
| `kimi-k2-thinking` | `kimi-k2.6` |
| `kimi-k2:1t` | `kimi-k2.6` |
| `minimax-m2` | `minimax-m3` |
| `glm-4.6` | `glm-5.1` |
| `qwen3-next:80b` | `qwen3.5` |
| `qwen3-vl:235b` | `qwen3.5` |
| `qwen3-vl:235b-instruct` | `qwen3.5` |
| `cogito-2.1:671b` | `deepseek-v4-flash` |
</Accordion>
</AccordionGroup>
For questions about Cloud accounts, privacy, authentication, and requests, see the [Cloud FAQ](/cloud/faq).

97
docs/cloud/api.mdx Normal file
View file

@ -0,0 +1,97 @@
---
title: Cloud API
description: Authenticate and call the Ollama Cloud API directly at https://ollama.com/api.
---
Call Cloud models directly through `https://ollama.com/api`. In this mode, `ollama.com` is the Ollama host and a local Ollama installation is not required.
## Authentication
Create an [API key](https://ollama.com/settings/keys), then set it as an environment variable:
```shell
export OLLAMA_API_KEY=your_api_key
```
Send the key as a bearer token in the `Authorization` header with every request.
## List models
```shell
curl https://ollama.com/api/tags \
-H "Authorization: Bearer $OLLAMA_API_KEY"
```
## Generate a response
<Tabs>
<Tab title="cURL">
```shell
curl https://ollama.com/api/chat \
-H "Authorization: Bearer $OLLAMA_API_KEY" \
-d '{
"model": "gpt-oss:120b",
"messages": [{"role": "user", "content": "Why is the sky blue?"}],
"stream": false
}'
```
</Tab>
<Tab title="Python">
Install the [Ollama Python library](https://github.com/ollama/ollama-python):
```shell
pip install ollama
```
```python
import os
from ollama import Client
client = Client(
host="https://ollama.com",
headers={"Authorization": "Bearer " + os.environ["OLLAMA_API_KEY"]},
)
messages = [{"role": "user", "content": "Why is the sky blue?"}]
for part in client.chat("gpt-oss:120b", messages=messages, stream=True):
print(part["message"]["content"], end="", flush=True)
```
</Tab>
<Tab title="JavaScript">
Install the [Ollama JavaScript library](https://github.com/ollama/ollama-js):
```shell
npm i ollama
```
```typescript
import { Ollama } from "ollama";
const ollama = new Ollama({
host: "https://ollama.com",
headers: {
Authorization: "Bearer " + process.env.OLLAMA_API_KEY,
},
});
const response = await ollama.chat({
model: "gpt-oss:120b",
messages: [{ role: "user", content: "Explain quantum computing" }],
stream: true,
});
for await (const part of response) {
process.stdout.write(part.message.content);
}
```
</Tab>
</Tabs>
For endpoint schemas and response fields, use the [API Reference](/api/introduction).

63
docs/cloud/faq.mdx Normal file
View file

@ -0,0 +1,63 @@
---
title: Cloud FAQ
sidebarTitle: FAQ
description: Frequently asked questions about Ollama Cloud accounts, authentication, privacy, and requests.
---
For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/faq).
## Does Ollama send my prompts and answers back to ollama.com?
Ollama runs locally. We don't see your prompts or data when you run local models.
When you use Cloud models, Ollama processes your prompts and responses to provide the service but does not store or log that content and never trains on it. Ollama collects basic account information and limited usage metadata that does not include prompt or response content. Ollama does not sell your data, and you can delete your account at any time.
To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/faq#how-do-i-disable-ollama-cloud-features).
## How do I manage the maximum number of requests the Ollama server can queue?
When you access Cloud models through a local Ollama server, requests can queue locally while the server is busy. If the queue is full, the server responds with a `503` overloaded error.
Set `OLLAMA_MAX_QUEUE` before starting the local server to change the maximum number of queued requests:
```shell
OLLAMA_MAX_QUEUE=1024 ollama serve
```
See [How do I configure Ollama server?](/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables.
## What is the difference between an API key and my Ollama Public Key?
An **API key** authenticates a program that calls `https://ollama.com/api` directly. Create and manage API keys in [Ollama settings](https://ollama.com/settings/keys). See [Cloud API authentication](/cloud/api#authentication) for an example.
Your **Ollama Public Key** identifies a local Ollama installation to ollama.com. It is used when you sign in locally to run Cloud models, push models, or pull private models.
## Where can I find my Ollama Public Key?
The Ollama Public Key is the public part of the key pair that lets your local Ollama instance communicate with [ollama.com](https://ollama.com).
You need it to:
- Push models to Ollama
- Pull private models to your machine
- Run models hosted in Ollama Cloud through your local Ollama installation
### Add the key to your account
Sign in from the Settings page in the macOS or Windows app, or sign in from the CLI:
```shell
ollama signin
```
You can also copy and paste the public key on the [Ollama Keys](https://ollama.com/settings/keys) page.
### Find the key on disk
| Operating system | Path to `id_ed25519.pub` |
| --- | --- |
| macOS | `~/.ollama/id_ed25519.pub` |
| Linux | `/usr/share/ollama/.ollama/id_ed25519.pub` |
| Windows | `C:\Users\<username>\.ollama\id_ed25519.pub` |
Replace `<username>` with your Windows user name.

59
docs/cloud/model-lifecycle.mdx Normal file
View file

@ -0,0 +1,59 @@
---
title: Cloud model lifecycle
description: Review upcoming and past Ollama Cloud model retirements and recommended replacements.
---
Ollama occasionally deprecates and retires older Cloud models as newer models become available. Tools and applications that depend on a retired model must be updated to use another model.
Impacted users are notified before a model is retired. Cloud model retirement does not affect local models.
## Upcoming retirements
| Retirement date | Model | Recommended alternative |
| --- | --- | --- |
| July 31, 2026 | `minimax-m2.5` | `minimax-m2.7` |
| July 31, 2026 | `kimi-k2.5` | `kimi-k2.6` |
## Past retirements
<AccordionGroup>
<Accordion title="July 15, 2026">
| Model | Recommended alternative |
| --- | --- |
| `deepseek-v3.1:671b` | `deepseek-v4-flash` |
| `deepseek-v3.2` | `deepseek-v4-flash` |
| `devstral-2:123b` | `mistral-large-3:675b` |
| `devstral-small-2:24b` | |
| `ministral-3:14b` | |
| `ministral-3:3b` | |
| `ministral-3:8b` | |
| `gemini-3-flash-preview` | `minimax-m3` |
| `gemma3:12b` | `gemma4:31b` |
| `gemma3:27b` | `gemma4:31b` |
| `gemma3:4b` | `gemma4:31b` |
| `glm-4.7` | `glm-5.2` |
| `glm-5` | `glm-5.2` |
| `minimax-m2.1` | `minimax-m3` |
| `qwen3-coder-next` | `qwen3.5:397b` |
| `qwen3-coder:480b` | `qwen3.5:397b` |
</Accordion>
<Accordion title="June 30, 2026">
| Model | Recommended alternative |
| --- | --- |
| `rnj-1:8b` | |
</Accordion>
<Accordion title="June 16, 2026">
| Model | Recommended alternative |
| --- | --- |
| `kimi-k2-thinking` | `kimi-k2.6` |
| `kimi-k2:1t` | `kimi-k2.6` |
| `minimax-m2` | `minimax-m3` |
| `glm-4.6` | `glm-5.1` |
| `qwen3-next:80b` | `qwen3.5` |
| `qwen3-vl:235b` | `qwen3.5` |
| `qwen3-vl:235b-instruct` | `qwen3.5` |
| `cogito-2.1:671b` | `deepseek-v4-flash` |
</Accordion>
</AccordionGroup>

94
docs/cloud/models.mdx Normal file
View file

@ -0,0 +1,94 @@
---
title: Use Cloud models from Ollama
sidebarTitle: Cloud models
description: Run Ollama Cloud models from the CLI, the local Ollama API, or the official Python and JavaScript libraries.
---
Cloud models are automatically offloaded to Ollama Cloud while remaining available to local tools and integrations through Ollama.
## Sign in
Cloud models require an account on [ollama.com](https://ollama.com). Sign in or create an account from the CLI:
```shell
ollama signin
```
Browse supported models in the [cloud model library](https://ollama.com/search?c=cloud).
## Run a Cloud model
<Tabs>
<Tab title="CLI">
```shell
ollama run gpt-oss:120b-cloud
```
</Tab>
<Tab title="Python">
Pull the Cloud model, then install the [Ollama Python library](https://github.com/ollama/ollama-python):
```shell
ollama pull gpt-oss:120b-cloud
pip install ollama
```
```python
from ollama import Client
client = Client()
messages = [{"role": "user", "content": "Why is the sky blue?"}]
for part in client.chat("gpt-oss:120b-cloud", messages=messages, stream=True):
print(part["message"]["content"], end="", flush=True)
```
</Tab>
<Tab title="JavaScript">
Pull the Cloud model, then install the [Ollama JavaScript library](https://github.com/ollama/ollama-js):
```shell
ollama pull gpt-oss:120b-cloud
npm i ollama
```
```typescript
import { Ollama } from "ollama";
const ollama = new Ollama();
const response = await ollama.chat({
model: "gpt-oss:120b-cloud",
messages: [{ role: "user", content: "Explain quantum computing" }],
stream: true,
});
for await (const part of response) {
process.stdout.write(part.message.content);
}
```
</Tab>
<Tab title="cURL">
Pull the Cloud model, then call it through the local Ollama API:
```shell
ollama pull gpt-oss:120b-cloud
```
```shell
curl http://localhost:11434/api/chat -d '{
"model": "gpt-oss:120b-cloud",
"messages": [{"role": "user", "content": "Why is the sky blue?"}],
"stream": false
}'
```
</Tab>
</Tabs>
To use Cloud without a local Ollama installation, call the [Cloud API directly](/cloud/api).

68
docs/docs.json
View file

@ -110,8 +110,7 @@
"group": "Get started",
"pages": [
"index",
"quickstart",
"/cloud"
"quickstart"
]
},
{
@ -127,19 +126,66 @@
]
},
{
"group": "More information",
"group": "Sample projects",
"pages": [
"/sample-projects/research-brief-agent"
]
}
]
},
{
"tab": "Cloud",
"groups": [
{
"group": "Get started",
"pages": [
"/cloud",
"/cloud/models",
"/cloud/api"
]
},
{
"group": "Operations",
"pages": [
"/cloud/model-lifecycle",
"/cloud/faq"
]
}
]
},
{
"tab": "Local",
"groups": [
{
"group": "Get started",
"pages": [
"/local",
"/macos",
"/linux",
"/windows",
"/docker"
]
},
{
"group": "Run and configure",
"pages": [
"/cli",
"/modelfile",
"/context-length",
"/linux",
"/macos",
"/windows",
"/docker",
"/context-length"
]
},
{
"group": "Customize models",
"pages": [
"/import",
"/faq",
"/modelfile"
]
},
{
"group": "Hardware and support",
"pages": [
"/gpu",
"/troubleshooting"
"/troubleshooting",
"/faq"
]
}
]

48
docs/faq.mdx
View file

@ -1,7 +1,11 @@
---
title: FAQ
title: Local FAQ
sidebarTitle: FAQ
description: Frequently asked questions about installing, configuring, and running Ollama locally.
---
For questions about accounts, authentication, and hosted models, see the [Cloud FAQ](/cloud/faq).
## How can I upgrade Ollama?
Ollama on macOS and Windows will automatically download updates. Click on the taskbar or menubar item and then click "Restart to update" to apply the update. Updates can also be installed by downloading the latest version [manually](https://ollama.com/download/).
@ -156,10 +160,6 @@ docker build -t ollama-with-ca .
docker run -d -e HTTPS_PROXY=https://my.proxy.example.com -p 11434:11434 ollama-with-ca
```
## Does Ollama send my prompts and answers back to ollama.com?
Ollama runs locally. We don't see your prompts or data when you run locally. When using cloud-hosted models, we process your prompts and responses to provide the service but do not store or log that content and never train on it. We collect basic account info and limited usage metadata to provide the service that does not include prompt or response content. We don't sell your data. You can delete your account anytime.
## How do I disable Ollama Cloud features?
Ollama can run in local only mode by disabling Ollama's cloud features. By turning off Ollama's cloud features, you will lose the ability to use Ollama's cloud models and web search.
@ -317,10 +317,6 @@ Alternatively, you can change the amount of time all models are loaded into memo
The `keep_alive` API parameter with the `/api/generate` and `/api/chat` API endpoints will override the `OLLAMA_KEEP_ALIVE` setting.
## How do I manage the maximum number of requests the Ollama server can queue?
If too many requests are sent to the server, it will respond with a 503 error indicating the server is overloaded. You can adjust how many requests may be queued by setting `OLLAMA_MAX_QUEUE`.
## How does Ollama handle concurrent requests?
Ollama supports two levels of concurrent processing. If your system has sufficient available memory (system memory when using CPU inference, or VRAM for GPU inference) then multiple models can be loaded at the same time. For a given model, if there is sufficient available memory when the model is loaded, it is configured to allow parallel request processing.
@ -368,40 +364,6 @@ How much the cache quantization impacts the model's response quality will depend
You may need to experiment with different quantization types to find the best balance between memory usage and quality.
## Where can I find my Ollama Public Key?
Your **Ollama Public Key** is the public part of the key pair that lets your local Ollama instance talk to [ollama.com](https://ollama.com).
You'll need it to:
* Push models to Ollama
* Pull private models from Ollama to your machine
* Run models hosted in [Ollama Cloud](https://ollama.com/cloud)
### How to Add the Key
* **Sign-in via the Settings page** in the **Mac** and **Windows App**
* **Sign‑in via CLI**
```shell
ollama signin
```
* **Manually copy & paste** the key on the **Ollama Keys** page:
[https://ollama.com/settings/keys](https://ollama.com/settings/keys)
### Where the Ollama Public Key lives
| OS | Path to `id_ed25519.pub` |
| :- | :- |
| macOS | `~/.ollama/id_ed25519.pub` |
| Linux | `/usr/share/ollama/.ollama/id_ed25519.pub` |
| Windows | `C:\Users\<username>\.ollama\id_ed25519.pub` |
<Note>
Replace &lt;username&gt; with your actual Windows user name.
</Note>
## How can I stop Ollama from starting when I login to my computer?
Ollama for Windows and macOS register as a login item during installation. You can disable this if you prefer not to have Ollama automatically start. Ollama will respect this setting across upgrades, unless you uninstall the application.

37
docs/index.mdx
View file

@ -1,26 +1,31 @@
---
title: Ollama documentation
sidebarTitle: Welcome
description: Learn what Ollama can do, choose cloud or local models, and find the right guide, integration, or API reference.
---
Start building with open models.
Build with open models in Ollama Cloud or on your own hardware.
Follow the [quickstart](/quickstart), then choose a model, integration, or API.
Follow the [quickstart](/quickstart), then choose the environment that matches your needs.
## Models
## Choose where models run
Run models locally or use larger models in Ollama's cloud.
Cloud and local models use the same Ollama tools and API shapes. The main difference is where inference runs.
<CardGroup cols={2}>
<Card title="Browse models" icon="star" href="https://ollama.com/search">
Find models for chat, coding, vision, embeddings, and reasoning.
<Card title="Cloud" icon="cloud" href="/cloud">
Run larger models without managing local compute, either from Ollama or through the Cloud API.
</Card>
<Card title="Cloud models" icon="cloud" href="/cloud">
Run larger models on Ollama's Cloud without the download.
<Card title="Local" icon="laptop" href="/local">
Install Ollama and run models on macOS, Windows, Linux, or Docker.
</Card>
</CardGroup>
## What you can build
Ollama supports [streaming](/capabilities/streaming), [tool calling](/capabilities/tool-calling), [structured outputs](/capabilities/structured-outputs), [vision](/capabilities/vision), [embeddings](/capabilities/embeddings), [thinking](/capabilities/thinking), and [web search](/capabilities/web-search).
## Next steps
Connect Ollama to an app, or build with the API.
@ -30,8 +35,12 @@ Connect Ollama to an app, or build with the API.
Connect Ollama to an app, editor, or agent.
</Card>
<Card title="First API request" icon="code" href="/api/introduction">
Learn the local and cloud base URLs, then send a request with `curl`.
<Card title="API reference" icon="code" href="/api/introduction">
Compare local and cloud base URLs, then send your first request.
</Card>
<Card title="Browse models" icon="star" href="https://ollama.com/search">
Find models for chat, coding, vision, embeddings, and reasoning.
</Card>
<Card title="Python library" icon="python" href="https://github.com/ollama/ollama-python">
@ -53,4 +62,12 @@ Connect Ollama to an app, or build with the API.
<Card title="Reddit" icon="reddit" href="https://reddit.com/r/ollama">
Join the Ollama subreddit.
</Card>
<Card title="X (Twitter)" icon="discord" href="https://twitter.com/ollama">
Join the Ollama X (Twitter).
</Card>
<Card title="Github" icon="discord" href="https://github.com/ollama/ollama">
Join the Ollama GitHub.
</Card>
</CardGroup>

57
docs/local.mdx Normal file
View file

@ -0,0 +1,57 @@
---
title: Run Ollama locally
sidebarTitle: Overview
description: Install, configure, and run Ollama models on your own macOS, Windows, Linux, or Docker environment.
---
Run models on your own hardware with Ollama. Local inference keeps model execution on the machine or infrastructure you control and does not require an Ollama account.
## Install Ollama
Choose the installation guide for your environment.
<CardGroup cols={2}>
<Card title="macOS" icon="apple" href="/macos">
Install the Ollama app on Apple silicon or Intel hardware.
</Card>
<Card title="Windows" icon="windows" href="/windows">
Install the native Windows application.
</Card>
<Card title="Linux" icon="linux" href="/linux">
Install Ollama with the install script or a manual package.
</Card>
<Card title="Docker" icon="docker" href="/docker">
Run Ollama in a container with CPU or GPU acceleration.
</Card>
</CardGroup>
## Run a local model
After installation, start a model from the terminal:
```shell
ollama run gemma4
```
Ollama also serves its local API at `http://localhost:11434/api` by default.
```shell
curl http://localhost:11434/api/chat -d '{
"model": "gemma4",
"messages": [{"role": "user", "content": "Why is the sky blue?"}],
"stream": false
}'
```
## Configure your environment
- Use the [CLI reference](/cli) to run, download, copy, and remove models.
- Adjust the [context length](/context-length) for agents and other long-context workloads.
- Review [hardware support](/gpu) for GPU compatibility and acceleration.
- [Import a model](/import) or create a customized model with a [Modelfile](/modelfile).
- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features.
For failures, start with [Troubleshooting](/troubleshooting).

30
docs/quickstart.mdx
View file

@ -1,10 +1,27 @@
---
title: Quickstart
description: Choose Ollama Cloud or a local installation and run your first model.
---
Install Ollama and get your first response.
Get your first response from a cloud or local model. The Ollama CLI and API work with both.
## 1. Download Ollama
## Choose an environment
<CardGroup cols={2}>
<Card title="Cloud" icon="cloud" href="/cloud">
Use larger models without providing your own GPU. Start from the Ollama CLI or call the Cloud API directly.
</Card>
<Card title="Local" icon="laptop" href="/local">
Run models on your own hardware. Start by installing Ollama for your operating system.
</Card>
</CardGroup>
## Run a model from the CLI
This path works with local models and cloud models.
### 1. Download Ollama
Ollama runs on macOS, Windows, and Linux.
@ -16,7 +33,7 @@ Ollama runs on macOS, Windows, and Linux.
Download Ollama
</a>
## 2. Open the menu
### 2. Open the menu
Run `ollama` in your terminal to open the interactive menu:
@ -29,7 +46,7 @@ From the menu you can:
- **Run a model** - Start an interactive chat
- **Launch tools** - [Claude Code](/integrations/claude-code), [OpenClaw](/integrations/openclaw), [VS Code](/integrations/vscode), and more
## 3. Start a chat
### 3. Start a chat
Run a model to start your first chat.
@ -37,9 +54,10 @@ Run a model to start your first chat.
ollama run gemma4
```
Cloud models work the same way:
Or sign in and run a cloud model:
```shell
ollama signin
ollama run gemma4:cloud
```
@ -57,4 +75,4 @@ To leave the chat, type:
## Next steps
Use a model with an [integration](/integrations), make an [API request](/api/introduction), or browse more [models](https://ollama.com/search).
Learn about [Cloud](/cloud) or [Local](/local), use a model with an [integration](/integrations), make an [API request](/api/introduction), or browse [models](https://ollama.com/search).

306
docs/sample-projects/research-brief-agent.mdx Normal file
View file

@ -0,0 +1,306 @@
---
title: Build a research brief agent
sidebarTitle: Research brief agent
description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research brief.
---
Build an agent that researches a question and turns its findings into a cited decision brief. This is useful for market research, policy summaries, product comparisons, event planning, and other tasks where current sources matter.
The project uses an Ollama Cloud model for reasoning and the Ollama web search and web fetch APIs for research. It runs entirely through Ollama Cloud, so you do not need a local model or GPU.
## What you will build
Given a question such as:
> What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance?
the agent will:
1. Turn the question into several focused searches.
2. Search the web and choose promising results.
3. Fetch source pages for more context.
4. Compare claims across sources.
5. Write a brief with links, caveats, and suggested follow-up questions.
The example uses `gpt-oss:120b`, but you can choose another tool-capable model returned by the Cloud API.
## Before you begin
You need:
- Python 3.10 or later
- An [Ollama account](https://ollama.com)
- An [Ollama API key](https://ollama.com/settings/keys)
The API key gives the script access to both the Cloud model and the [web search tools](/capabilities/web-search). Treat it like a password and do not add it to source control.
## 1. Set up the project
Create a project directory and a Python virtual environment:
<Tabs>
<Tab title="macOS and Linux">
```shell
mkdir research-brief-agent
cd research-brief-agent
python3 -m venv .venv
source .venv/bin/activate
```
</Tab>
<Tab title="Windows PowerShell">
```powershell
mkdir research-brief-agent
cd research-brief-agent
py -m venv .venv
.venv\Scripts\Activate.ps1
```
</Tab>
</Tabs>
Install the Ollama Python library:
```shell
pip install --upgrade ollama
```
Set your API key for the current terminal session:
<Tabs>
<Tab title="macOS and Linux">
```shell
export OLLAMA_API_KEY=your_api_key
```
</Tab>
<Tab title="Windows PowerShell">
```powershell
$env:OLLAMA_API_KEY="your_api_key"
```
</Tab>
</Tabs>
<Note>
Environment variables set this way last only for the current terminal session. Use your operating system's secret manager for a persistent setup.
</Note>
## 2. Check Cloud access
List the models available to your account:
```shell
curl https://ollama.com/api/tags \
-H "Authorization: Bearer $OLLAMA_API_KEY"
```
Look for `gpt-oss:120b` in the response. If it is not available, choose another Cloud model that supports tool calling and set its name with `OLLAMA_MODEL`:
<Tabs>
<Tab title="macOS and Linux">
```shell
export OLLAMA_MODEL=your_model_name
```
</Tab>
<Tab title="Windows PowerShell">
```powershell
$env:OLLAMA_MODEL="your_model_name"
```
</Tab>
</Tabs>
## 3. Create the agent
Save the following as `research_agent.py`:
```python
import os
import sys
from ollama import Client, web_fetch, web_search
MODEL = os.getenv("OLLAMA_MODEL", "gpt-oss:120b")
MAX_TOOL_ROUNDS = 8
SYSTEM_PROMPT = """You are a careful research agent.
Research the user's question before answering. Search broadly, then fetch the
most useful pages. Prefer primary sources, original studies, official reports,
and sources that clearly explain their methods.
Your final answer must contain:
1. An executive summary
2. Key findings, including disagreements between sources
3. Limitations and missing evidence
4. Practical next steps
5. A Sources section with Markdown links
Attach a source link to every important factual claim. Never invent a citation.
If the available evidence does not support a conclusion, say so explicitly.
"""
def run_tool(name: str, arguments: dict) -> str:
"""Run one tool selected by the model and return text for the next turn."""
tools = {
"web_search": web_search,
"web_fetch": web_fetch,
}
tool = tools.get(name)
if tool is None:
return f"Unknown tool: {name}"
print(f"Tool: {name}({arguments})")
result = tool(**arguments)
# Large pages can crowd useful evidence out of the model's context.
return str(result)[:12000]
def research(question: str) -> str:
api_key = os.environ.get("OLLAMA_API_KEY")
if not api_key:
raise RuntimeError("Set OLLAMA_API_KEY before running the agent.")
client = Client(
host="https://ollama.com",
headers={"Authorization": f"Bearer {api_key}"},
)
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": question},
]
for _ in range(MAX_TOOL_ROUNDS):
response = client.chat(
model=MODEL,
messages=messages,
tools=[web_search, web_fetch],
think=True,
)
messages.append(response.message)
if not response.message.tool_calls:
return response.message.content
for call in response.message.tool_calls:
name = call.function.name
result = run_tool(name, call.function.arguments)
messages.append(
{
"role": "tool",
"tool_name": name,
"content": result,
}
)
# Force a final report if the model uses the full research budget.
messages.append(
{
"role": "user",
"content": "Stop researching and write the final cited brief now.",
}
)
response = client.chat(model=MODEL, messages=messages, think=True)
return response.message.content
if __name__ == "__main__":
default_question = (
"What have four-day workweek pilots since 2022 reported about "
"employee wellbeing and business performance?"
)
question = " ".join(sys.argv[1:]) or default_question
print(research(question))
```
The model receives two tools as Python functions. Ollama converts those functions into tool definitions, the Cloud model decides when and how to call them, and the script returns each tool result to the model. The loop ends when the model produces a response without another tool call.
`MAX_TOOL_ROUNDS` prevents an open-ended research loop. The final request removes the tools and asks for a report if the agent uses its entire tool budget.
## 4. Run the project
Run the agent with the example research question:
```shell
python research_agent.py
```
Or provide your own question:
```shell
python research_agent.py "What evidence supports later high school start times?"
```
During the run, the script prints each tool call. A typical trace looks like this:
```text
Tool: web_search({'query': 'four-day workweek pilot 2022 study results'})
Tool: web_search({'query': 'four-day week trial company revenue retention report'})
Tool: web_fetch({'url': 'https://example.org/report'})
```
Search queries and sources will vary between runs. That is expected: the model chooses its next action from the evidence it has already gathered.
## 5. Review the result
Expect a Markdown report with this general shape:
```text
# Research brief
## Executive summary
A concise answer to the research question.
## Key findings
Findings grouped by theme, with links attached to factual claims.
## Limitations
Gaps in the available evidence, methodology concerns, and conflicting results.
## Practical next steps
Actions or questions that follow from the evidence.
## Sources
A list of the pages used in the report.
```
The first run should produce a useful draft, not an unquestionable final answer. Check that links open, quoted numbers match their sources, and the report distinguishes published evidence from the model's interpretation.
<Warning>
Web results can be incomplete, outdated, or wrong. Review the original sources before using the brief for medical, legal, financial, employment, or other high-impact decisions.
</Warning>
## What happens at each stage
| Stage | What the Cloud model does | What you should expect |
| --- | --- | --- |
| Plan | Breaks the question into searchable claims | Several queries covering different aspects of the topic |
| Search | Calls `web_search` and evaluates result snippets | A visible tool trace; some searches may be discarded |
| Read | Calls `web_fetch` for promising pages | More detailed evidence from a smaller set of sources |
| Compare | Looks for agreement, conflicts, and missing context | Findings that separate strong evidence from uncertainty |
| Synthesize | Writes the requested report | A readable brief with citations, caveats, and next steps |
## Improve the agent
Try these changes after the basic project works:
- Change `SYSTEM_PROMPT` to require a particular audience, length, or report format.
- Ask the agent to prefer sources from specific domains or a date range.
- Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs.
- Save the final string to a Markdown file for sharing.
- Add a human approval step before the agent fetches unfamiliar domains.
See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces.