# How to Use a Local Milvus Deployment with Claude Context Instead of Zilliz Cloud

> Learn how to use a local Milvus deployment with Claude Context by setting the MILVUS_ADDRESS environment variable. Avoid Zilliz Cloud dependency for a fully self-hosted solution.

- Repository: [Zilliz/claude-context](https://github.com/zilliztech/claude-context)
- Tags: how-to-guide
- Published: 2026-04-22

---

**Yes, Claude Context supports fully local Milvus deployments by configuring the `MILVUS_ADDRESS` environment variable to point to your self-hosted server, requiring no token and no Zilliz Cloud dependency.**

The `zilliztech/claude-context` repository provides flexible vector database adapters that work with any Milvus endpoint, not just Zilliz Cloud. By leveraging the local deployment support built into the core SDK, you can run Claude Context entirely on-premises using a self-hosted Milvus server accessible via gRPC or REST APIs.

## Architecture Support for Local Milvus Instances

Claude Context abstracts vector storage behind a `VectorDatabase` interface, with two Milvus-specific implementations that both support local deployments through explicit address resolution.

### MilvusVectorDatabase (gRPC Implementation)

In [`packages/core/src/vectordb/milvus-vectordb.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/vectordb/milvus-vectordb.ts), the `MilvusVectorDatabase` class implements the `VectorDatabase` interface using the official Milvus gRPC SDK. The constructor accepts a `MilvusConfig` object containing an optional `address` field. The `resolveAddress()` method (lines 13-20) prioritizes the explicit `config.address` value; when provided, it bypasses token-based address resolution entirely. For local deployments, simply pass `address: "localhost:19530"` to establish a direct gRPC connection to your self-hosted server.

### MilvusRestfulVectorDatabase (REST Implementation)

For environments where native gRPC bindings cannot load—such as VS Code extensions or Chrome extensions—the `MilvusRestfulVectorDatabase` class in [`packages/core/src/vectordb/milvus-restful-vectordb.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/vectordb/milvus-restful-vectordb.ts) provides an HTTP-based alternative. The `resolveAddress()` implementation (lines 93-100) follows the same logic as the gRPC version, checking for an explicit address before attempting token resolution. After resolving the address, it constructs a base URL in the format `http://<address>/v2/vectordb`. Setting `address: "localhost:19530"` directs the client to the Milvus REST gateway running locally.

### Configuration via Environment Variables

The configuration manager reads from environment variables or a global `~/.context/.env` file. As documented in [`docs/getting-started/environment-variables.md`](https://github.com/zilliztech/claude-context/blob/main/docs/getting-started/environment-variables.md), setting `MILVUS_ADDRESS` without a `MILVUS_TOKEN` configures Claude Context to connect to a local instance. The VS Code extension mirrors this logic in [`packages/vscode-extension/src/config/configManager.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/config/configManager.ts), reading Milvus settings from the IDE's configuration.

## Setting Up Local Milvus with Docker

Prerequisites documentation in [`docs/getting-started/prerequisites.md`](https://github.com/zilliztech/claude-context/blob/main/docs/getting-started/prerequisites.md) explicitly includes a "Local Milvus (Advanced)" option with Docker installation instructions.

1. Start Milvus locally using Docker (the simplest method):

```bash
docker run -d -p 19530:19530 -p 19121:19121 milvusdb/milvus:latest

```

2. Export the address or add it to `~/.context/.env`:

```bash
export MILVUS_ADDRESS=localhost:19530

```

3. Run Claude Context. The SDK automatically instantiates either `MilvusVectorDatabase` or `MilvusRestfulVectorDatabase` using the provided address, with no token required.

## Code Example: Switching from Zilliz Cloud to Local Milvus

The repository's basic usage example in [`examples/basic-usage/index.ts`](https://github.com/zilliztech/claude-context/blob/main/examples/basic-usage/index.ts) demonstrates how to select the vector database implementation and configure the address. This pattern works identically for local deployments by omitting the token and specifying the local address:

```typescript
import {
  Context,
  MilvusVectorDatabase,          // gRPC client
  MilvusRestfulVectorDatabase,    // REST client
  AstCodeSplitter,
} from '@zilliz/claude-context-core';
import { envManager } from '@zilliz/claude-context-core';

// Choose the implementation you need (gRPC is the default, REST is safe for VS Code extensions)
const useRestful = false;                     // set true if you need the REST version
const milvusAddress = envManager.get('MILVUS_ADDRESS') ?? 'localhost:19530';

const vectorDb = useRestful
  ? new MilvusRestfulVectorDatabase({ address: milvusAddress })
  : new MilvusVectorDatabase({ address: milvusAddress });

const splitter = new AstCodeSplitter(/* chunkSize */ 2500, /* overlap */ 300);
const ctx = new Context({
  vectorDatabase: vectorDb,
  codeSplitter: splitter,
  supportedExtensions: ['.ts', '.js', '.py'],
});

// Index and search as usual – no other changes needed
await ctx.indexCodebase('/path/to/your/project');
const results = await ctx.semanticSearch('/path/to/your/project', 'search query');

```

When running locally, the `MilvusConfig` object receives only the `address` property, allowing the `resolveAddress()` method to return your local server endpoint immediately without attempting cloud authentication.

## Key Implementation Files

Understanding these source files helps when debugging local connections:

- **[`packages/core/src/vectordb/milvus-vectordb.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/vectordb/milvus-vectordb.ts)**: gRPC-based implementation; contains `resolveAddress()` logic for direct connections
- **[`packages/core/src/vectordb/milvus-restful-vectordb.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/vectordb/milvus-restful-vectordb.ts)**: REST-based implementation; constructs HTTP URLs from resolved addresses
- **[`packages/vscode-extension/src/config/configManager.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/vscode-extension/src/config/configManager.ts)**: VS Code-specific configuration reading
- **[`examples/basic-usage/index.ts`](https://github.com/zilliztech/claude-context/blob/main/examples/basic-usage/index.ts)**: Reference implementation showing implementation selection logic
- **[`docs/getting-started/prerequisites.md`](https://github.com/zilliztech/claude-context/blob/main/docs/getting-started/prerequisites.md)**: Local deployment instructions and Docker guides
- **[`docs/getting-started/environment-variables.md`](https://github.com/zilliztech/claude-context/blob/main/docs/getting-started/environment-variables.md)**: Complete `MILVUS_ADDRESS` and `MILVUS_TOKEN` documentation

## Summary

- Claude Context supports fully **local Milvus deployments** by configuring the `MILVUS_ADDRESS` environment variable
- Two implementations exist: `MilvusVectorDatabase` for gRPC and `MilvusRestfulVectorDatabase` for HTTP-based connections
- No token is required for local deployments; the `resolveAddress()` method uses the explicit address when provided
- Docker provides the quickest path to running Milvus locally on `localhost:19530`
- The architecture in `zilliztech/claude-context` intentionally abstracts the vector database layer, making Zilliz Cloud optional rather than mandatory

## Frequently Asked Questions

### Does Claude Context require Zilliz Cloud to function?

No. According to the source code in [`packages/core/src/vectordb/milvus-vectordb.ts`](https://github.com/zilliztech/claude-context/blob/main/packages/core/src/vectordb/milvus-vectordb.ts), the SDK only requires a reachable Milvus endpoint. By setting `MILVUS_ADDRESS` to a local server such as `localhost:19530`, Claude Context connects directly to your self-hosted instance without any cloud dependency.

### Which should I use for a local deployment: gRPC or REST?

Use `MilvusVectorDatabase` (gRPC) for standalone Node.js applications where native bindings load successfully. Use `MilvusRestfulVectorDatabase` (REST) for browser extensions or VS Code extensions where gRPC native modules cannot execute. Both support local deployments via the same `address` configuration parameter.

### What port does local Milvus use by default?

The standard Milvus deployment exposes gRPC on port **19530** and the REST API on the same port (or sometimes port **19121** for legacy REST). The Docker run command `docker run -p 19530:19530` maps this default port, which you then reference as `localhost:19530` in your `MILVUS_ADDRESS` configuration.

### Can I run Claude Context completely offline with local Milvus?

Yes, once the local Milvus server is running and Claude Context is configured with `MILVUS_ADDRESS` pointing to that local instance, the system operates entirely offline without internet connectivity or Zilliz Cloud authentication. The token parameter in `MilvusConfig` remains optional for local deployments.