# Stellara

[![PR CI](https://github.com/sebastian-software/stellara/actions/workflows/pr-ci.yml/badge.svg)](https://github.com/sebastian-software/stellara/actions/workflows/pr-ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Stellara is a self-hosted AI tool gateway for Firecrawl, Exa, Qdrant, and an embeddings backend. It exposes one token-protected HTTP and Model Context Protocol (MCP) interface for LLM clients such as Claude Desktop and ChatGPT connectors.

The gateway centralizes upstream credentials, authentication, rate limits, response validation, and network safeguards. It also provides Playwright browser sessions, per-user vector memory, and domain availability checks.

## Capabilities

- **`web_*`** — search, scrape, crawl, extract, and make guarded HTTP or GraphQL requests.
- **`browser_*`** — run interactive Playwright sessions for navigation, forms, screenshots, PDFs, and JavaScript evaluation.
- **`memory_*`** — store and retrieve per-user context through embeddings and Qdrant.
- **`domain_availability`** — check domain registration through RDAP with a WHOIS fallback.
- **OAuth 2.1 and MCP** — connect token-based clients or OAuth-capable MCP clients through one gateway.

See the [tool reference](docs/user-guide/tools.md) for the complete catalog.

## Requirements

- Node.js 24 or newer
- pnpm 10.33.4 through Corepack
- Provider credentials for the features you enable
- Docker for the container deployment

## Local development

```bash
corepack enable
pnpm install
cp .env.example .env
```

Set a public base URL, at least one `STELLARA_TOKEN_<USERID>`, and the required Firecrawl values in `.env`. Optional Exa, Qdrant, and embeddings credentials enable their matching tool families.

Start the development server:

```bash
pnpm dev
```

The health endpoint is available at `http://localhost:8787/health` unless `PORT` is changed.

## Container deployment

The supported container image is `ghcr.io/sebastian-software/stellara`. Versioned releases publish a stable patch tag plus the moving minor and `latest` tags.

Copy `.env.example` to `.env`, configure the external proxy network, prepare `stellara-data/` for UID/GID 999, and then start the service:

```bash
docker compose up -d
```

Read the [operations guide](docs/operations/betrieb.md) before exposing the service. It covers proxy trust, OAuth persistence, backup, and recovery.

## Development and tests

The required local quality gate is:

```bash
pnpm agent:check
```

This command runs type checking, linting, formatting verification, and the hermetic unit suite. Live provider tests are optional, local-only, and require credentials supplied through normal environment variables:

```bash
pnpm test:integration
```

GitHub Actions never receives or runs these integration credentials.

## Documentation

- [User guide](docs/user-guide/README.md)
- [Tool reference](docs/user-guide/tools.md)
- [Development guide](docs/developer-guide/entwicklung.md)
- [Tool API](docs/developer-guide/tool-api.md)
- [Test strategy](docs/developer-guide/tests.md)
- [Architecture](docs/developer-guide/stellara-konzept.md)
- [Operations](docs/operations/betrieb.md)
- [Release process](docs/operations/release-prozess.md)

Some in-depth documentation is currently available in German. Translation work is tracked in the public issue tracker.

## Contributing and support

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Use GitHub Issues for reproducible bugs and focused feature proposals. See [SUPPORT.md](SUPPORT.md) for the project support policy.

Report security vulnerabilities privately as described in [SECURITY.md](SECURITY.md). Do not disclose vulnerabilities in public issues.

## License

Stellara is available under the [MIT License](LICENSE).